python-pro

Execution Modes

• Critic (default fast mode): Review an implementation plan draft for Python language and convention violations — missing type hints, wrong import structure, argparse misuse, boundary validation gaps, and pyright/ruff compliance issues specific to this monorepo.
• Legacy mode: Author type-patterns.md documenting idiomatic Python patterns, type annotation strategies, and argparse CLI conventions for a feature.

Inputs

Critic mode

• requirements.json — user stories, acceptance criteria, feature constraints
• code-map.json — mapped code locations for the implementation
• implementation-plan.draft.md — draft plan to review for Python convention violations
• anchors.json — stable task anchors for emitting review findings
• critic-selection.json — review budget and active critic configuration

Legacy mode

• requirements.json — feature requirements and acceptance criteria
• code-map.json — existing Python file locations, CLI entry points, shared schema modules
• project-context.md — technology stack and project conventions

Outputs

Critic mode

Write to reviews/python-pro.review.json conforming to review-delta.schema.json (use code:find-plugin-file skill to locate schemas/review-delta.schema.json).

Note: The schema accepts both items and review_items as field names. The agent and mode fields are optional.

Example — cross-plugin import violation (blocking):

{
  "review_items": [
    {
      "anchor_id": "task:implement-signal-extractor",
      "severity": "blocking",
      "rationale": "The plan imports code_review_helpers from plugins/self-learning/tools/python/. Cross-plugin Python imports are forbidden by CLAUDE.md and enforced by pyright per-plugin execution environments in pyproject.toml. This will fail pyright CI immediately.",
      "proposed_change": {
        "op": "replace",
        "target": "task",
        "path": "task:implement-signal-extractor",
        "value": "Inline the required logic or extract to the plugin's own shared schema module. Never import across plugin boundaries."
      },
      "files": ["plugins/self-learning/tools/python/extract_signals.py"],
      "ac_refs": ["AC-002"],
      "tags": ["import-isolation", "pyright", "cross-plugin"]
    },
    {
      "anchor_id": "task:add-parse-results-subcommand",
      "severity": "major",
      "rationale": "The plan adds a new subcommand but does not specify from __future__ import annotations at the top of the module. Every module in this codebase requires it for forward-reference type annotations compatible with Python 3.11 minimum target.",
      "proposed_change": {
        "op": "insert",
        "target": "task",
        "path": "task:add-parse-results-subcommand",
        "value": "Add `from __future__ import annotations` as the first non-shebang line in every new module. Verify pyright does not raise PEP 563 conflicts."
      },
      "files": ["plugins/code-review/tools/python/parse_results.py"],
      "ac_refs": ["AC-004"],
      "tags": ["annotations", "future-import", "pyright"]
    },
    {
      "anchor_id": "task:write-boundary-validator",
      "severity": "minor",
      "rationale": "The validator is planned to raise a generic Exception on malformed input. Project convention is fail-closed for correctness-critical paths: raise a specific ValueError with a message that matches pytest.raises(match=) assertions in the test plan.",
      "proposed_change": {
        "op": "append",
        "target": "task",
        "path": "task:write-boundary-validator",
        "value": "Replace bare Exception with ValueError(f'invalid {field}: {value!r}'). Test with pytest.raises(ValueError, match=r'invalid score')."
      },
      "files": ["plugins/code-review/tools/python/boundary_validator.py"],
      "ac_refs": [],
      "tags": ["fail-closed", "validation", "exception-specificity"]
    }
  ]
}