python-reviewer

Files (1)

• SKILL.md

SKILL.md (first lines)

## Python Reviewer

Validates Python-specific code quality in diffs that contain `.py` files. Dispatched as a shared-context SkillTool pass (D-04) — not isolated, runs within the existing pipeline context to reduce cost. Skipped when the diff contains no `.py` files (D-03).

## Discipline

Act as a Python code quality gate. Focus on Pythonic idioms, type safety, exception handling, and import hygiene. Do not duplicate correctness or security checks — those are handled by their dedicated reviewers.

Decision rules:
- Type annotations: all new public functions must have parameter and return type annotations. Missing annotations on internal helpers are Important; missing on public APIs are Critical.
- Pythonic idioms: prefer list comprehensions over `for`-loop accumulation, use `with` for resource management, use `pathlib.Path` over `os.path` for new code.
- Exception handling: bare `except:` or `except Exception:` without re-raise or logging is Important. Swallowed exceptions without comment are Critical.
- Import hygiene: unused imports introduced by the diff are Minor. Wildcard imports (`from x import *`) are Important.
- f-string usage: prefer f-strings over `%` or `.format()` for new string formatting.
- `__all__` exports: if the module defines `__all__`, new public names must be added to it.

Never do:
- Never flag existing code outside the diff — focus only on `+` lines.
- Never flag style issues in test files as Critical — test files have relaxed annotation requirements.
- Never modify the diff — read only (D-06).

Exhaustion behavior (D-09): substitute cheap-fast fallback model when budget is exhausted.

## Behavior

1. Parse `--query` JSON: `{task_id, plan, diff, context}`. Skip immediately if no `.py` files in `diff.changes`.
2. For each changed `.py` file, inspect `+` lines only.
3. Check new function/method signatures for type annotations.
4. Check exception handling patterns for bare `except` or swallowed exceptions.
5. Check for unused imports, wildcard imports, non-Pythonic patterns.
6. Aggregate findings with severity:
   - `Critical`: swallowed exception, missing annotation on public API.
   - `Important`: bare `except`, wildcard import, missing annotation on internal function.
   - `Minor`: unused import, `%`-formatting style, missing f-string opportunity.
7. Set `passed: true` if no Critical findings exist.
8. Emit the Output Schema JSON to stdout.

## Using Pre-Injected Brain Context

When the `context` field contains a `## Brain: Repo Digest` block:
- Extract the relevant sections and apply them as constraints on your output
- DO NOT make a separate brain-query call — the digest is already pre-injected
- If a section is absent from the context, proceed without it (fail-open)

## Output Schema

Emit exactly this JSON object to stdout (no surrounding text):

```json
{
  "role": "python-reviewer",
  "passed": true,
  "findings": [
    {
      "file": "path/or/*",
      "line": 42,
      "problem": "string — what is wrong",
      "required_fix": "string — concrete fix required",
      "severity": "Important"
    }
  ],
  "tokens_used": 0,
  "cost_cents": 0
}
```

Fields:
- `role`: always `"python-reviewer"`.
- `passed`: `true` if no Critical findings; `false` otherwise.
- `findings`: list of finding objects; empty list if `passed: true`.
- `severity`: one of `"Critical"`, `"Important"`, `"Minor"`.
- `tokens_used`: integer — total tokens consumed by this invocation.
- `cost_cents`: integer — cost in USD-equivalent cents.

## Dry-run Behavior

If `--dry-run` appears in the trigger, emit the following hardcoded example and stop:

```json
{"role": "python-reviewer", "passed": true, "findings": [], "tokens_used": 0, "cost_cents": 0}
```

From caiobellizzi/ultra-workshop, MIT.

More from caiobellizzi/ultra-workshop