diagnostic-review

Diagnostic Review

Path B-deferred features — currently not implemented: This skill's body references several mechanisms (/watch threshold dispatch, noise-curator agent curation, /baseline persistence, the diagnostic-fixer agent, and the dispatch_fixer / baseline_diff custom MCP tools) that belong to Path B-deferred design per docs/superpowers/specs/2026-05-16-toolkit-pivot-path-b-decision.md. References to these mechanisms below describe forward-looking design intent, not active behavior. The shipped surface is: per-pass diagnostic triage (lint, typecheck, stats, explain, rule, configure), AST-scoped findings, in-band .toolkit.local.md suppression-list reading, and severity-aware payload assembly.

Purpose

Triage diagnostic output from the python-toolkit's bundled language servers and CLI checkers (ruff for lint, ty for type-checking). Categorize each finding by severity, scope it to its containing function or module via tree-sitter, suggest a fix, and route the stream through the project's noise-suppression layer so already-suppressed codes are filtered before the user ever sees them.

This skill is the single entry point for every diagnostic flavor in the python-toolkit. It is invoked directly by the user-facing per-pass skills (/check, /typecheck, /stats, /explain, /rule, /configure) with a pass: argument, AND it auto-activates when ruff or ty output appears in a recent tool result without an explicit user prompt. The body below is the contract for both modes — there is no second skill to keep in sync.

The skill collapses what was previously six separate command bodies into one shared procedure. The per-pass skills are now thin shims (~10 lines each) that invoke Skill(skill: "python-toolkit:diagnostic-review") with the pass selector. All real triage logic lives here and in references/procedure.md.

Usage

To invoke from a per-pass skill or directly, pass pass: as an argument:

• pass: lint — run the lint pass via ruff check. Surfaces violations grouped by code, with severity bucketing (E/F → error, W/I/N → warning, conventional codes → info). Honors --statistics shape when the caller asks for counts only. Returns the structured triage block described under Output Format below.
• pass: typecheck — run type-checking via ty check. Groups errors by category (missing imports, type incompatibilities, unresolved references, attribute-access on Optional, parameter-type mismatches). Falls through to pyright only if ty is not on PATH AND the project's .toolkit.local.md does not pin ty. Honors the ty-coverage-gap flag from .toolkit.local.md to soften messaging on Pydantic/Django/SQLAlchemy projects where ty is known to under-report.
• pass: stats — count violations by code without per-finding triage. Equivalent to ruff check --statistics . plus ty check --summary when both are present. Returns a ranked table sorted by count descending. This is the cheapest pass — no AST-scope walking, no suppression filtering applied to individual findings (the counts include suppressed entries marked with a [suppressed] tag).
• pass: explain CODE — explain a specific diagnostic code. For ruff codes (e.g. F401, E501, B006, UP007), wraps ruff rule <code>. For ty codes, queries the bundled LSP-MCP server's diagnostic-explanation endpoint when the bridge is running; otherwise opens the relevant section of references/codes.md.
• pass: rule CODE — alias for explain CODE. Preserved for the legacy /rule slash-command surface.
• pass: configure — scaffold or update the project's .claude/python-toolkit.local.md noise-suppression and /watch config. When a tier classifier has not yet run, it runs the auto-detect pass first and prompts the user to confirm or override the proposed tier (configured / partial / unconfigured + the orthogonal ty-coverage-gap flag). When the file already exists, this pass diffs the proposed updates against the current contents and asks for per-section confirmation.

Auto-Activation Triggers

The skill activates without a user prompt when its description: heuristic matches a recent tool result. Concrete trigger patterns:

• Lint/format markers: [*] fixable with --fix, [*] N fixable with the --fix option, Found N error(s) (ruff format).
• Ruff diagnostic codes: any line matching the regex ^\S+:\d+:\d+: [A-Z]+\d+\s (e.g. src/foo.py:12:5: F401 ...).
• ty diagnostic markers: lines containing error[<code>]: or warning[<code>]: where <code> is a ty diagnostic identifier; also bare error: followed by a Python type-error idiom (is not assignable to, has no attribute, expects X arguments, got Y).
• Build/test fallout that surfaces lint or typecheck output transitively (e.g. pytest collection errors revealing import-time ty errors).

When a trigger fires, the skill runs pass: lint or pass: typecheck (whichever matches the trigger) on the file(s) referenced in the tool result, applies suppression filtering, and surfaces the structured triage block. The skill does NOT auto-fix on activation — that requires either an explicit user request or a /watch threshold rule routing through the diagnostic-fixer agent.

Severity-Aware AST Scoping

Diagnostics surfaced to the user (and to downstream agents like diagnostic-fixer) are AST-scoped, not just file:line:col. The scope-walking depth depends on diagnostic severity, which bounds payload size: errors get rich context, warnings get medium context, hints stay cheap.

Severity	Scope walked	Rationale
error	up to module level (full file)	Type errors propagate; cross-function context is essential for fix accuracy
warning	containing function or method	Most lint warnings are local to a function body; surrounding class context rarely changes the fix
info / hint	affected line plus 2 lines of context	Style nits don't need scope walking; cheap context keeps the payload small

Tree-sitter is the load-bearing dependency for scope extraction. When tree-sitter cannot parse the file (syntax error, exotic encoding, generated source), the skill degrades to line-level scope and flags scope_degraded: true in the output.

Plan-Mode Behavior

The skill checks the harness permission mode at activation. When the session is in plan mode, behavior differs from full-execution mode:

• No agent dispatch. Even if /watch thresholds would normally fire diagnostic-fixer, the skill returns an advisory "would-have-dispatched" report and exits.
• No inline-validation hook firing. The PostToolUse(Edit|Write) chain in hooks/hooks.json is a no-op in plan mode regardless of .toolkit.local.md settings.
• Statusline cache writes still occur, so the bottom-of-screen counts stay live.
• Terminal summary uses advisory framing ("you have 7 unresolved imports — consider whether this affects the plan you're designing") rather than imperative framing ("fix these 7 imports").

Outside plan mode, the skill applies its full behavior including agent dispatch when threshold rules in .toolkit.local.md request it.

Output Format

Every pass returns a structured triage block. The block is YAML for downstream-agent consumption and is rendered to a human-readable summary for the user:

pass: lint | typecheck | stats | explain | rule | configure
project_tier: configured | partial | unconfigured
ty_coverage_gap: true | false
suppressions_active: <count>
findings:
  - file: <relative-path>
    line: <int>
    column: <int>
    code: <e.g. F401, E501, ty-missing-attribute>
    severity: error | warning | info | hint
    message: <one-line>
    scope:
      kind: module | function | line
      name: <function-or-class-name-or-null>
      source: |
        <AST-scoped excerpt>
    suggested_fix: <one-line or null>
    suppressed: false  # true entries are omitted unless pass: stats
totals:
  error: <int>
  warning: <int>
  info: <int>
  hint: <int>
  suppressed: <int>

The human-readable rendering bucket-counts by severity at the top, lists findings grouped by file (errors first, then warnings, then hints), and footnotes the suppression count so the user knows what was filtered out. When pass: stats is used, the findings array is omitted and the totals block is replaced by a per-code ranked table.

Integration with Surrounding Components

The skill sits at the centre of the python-toolkit's diagnostic stack:

• Per-pass skills (/check, /typecheck, /stats, /explain, /rule, /configure) invoke this skill via Skill(skill: "python-toolkit:diagnostic-review", pass: "<selector>"). The slash-command surface is preserved across the migration; the per-pass skills are thin wrappers, not duplicate logic.
• /watch filter+dispatch layer consumes the same triage block. When threshold rules in .toolkit.local.md cross their bucket count, /watch invokes the diagnostic-fixer agent with the AST-scoped payload (severity-aware scope already applied here).
• Suppression layer (.toolkit.local.md) is read on every invocation. Entries matching code + optional file-glob are stripped from findings before the human-readable rendering. The noise-curator agent uses the same file; this skill never edits it.
• Bundled LSP-MCP server (lsp-mcp-python) is the preferred diagnostic source when shipped (plan 5.2, in flight). Path B-reduced tool surface: get_diagnostics (karellen-standard) + custom tools suppress_diagnostic (write-only; appends to .toolkit.local.md) and tier_report (read-only; auto-detect tier + override summary). baseline_diff and dispatch_fixer were dropped per Path B. When the MCP server is not running, the skill falls back to direct ruff check --output-format=json and ty check --output-format=concise invocations.
• Baseline persistence (memory-keeper-backed; see /baseline) is consulted when the user asks "what's new" or when /watch requests baseline-aware prioritization. The skill itself does not write baselines — that is /baseline capture's job.

Procedure

For the full triage procedure (project-tier detection, suppression filter application, AST-scoped payload assembly, output formatting), load references/procedure.md.

For the diagnostic code reference (top ruff E/F/W codes and known ty diagnostic identifiers), load references/codes.md only when explaining a specific code or when the user asks for a code overview.

For the suppression-list curation flow (used when the noise-curator agent prompts to remove a stale entry), load references/curation.md.

Resources

• references/procedure.md — canonical triage procedure (project-tier detection, suppression filter, AST-scoped payload, output formatting)
• references/codes.md — diagnostic code reference (top 20 ruff codes; expand on demand)
• references/curation.md — suppression-list curation flow (mirrors the noise-curator agent's prompts)

Planned resources (deferred — chore 2026-05-16-lsp-mcp-bridge-contract, chore 45)

The following helpers depend on the LSP-MCP bridge contract that has not yet shipped. They will land in a follow-up chore once the bridge is in place:

• scripts/parse_ruff_json.py — fast deterministic parser for ruff check --output-format=json
• scripts/ast_scope.py — tree-sitter helper extracting the containing scope for a diagnostic given (file, line)

Until those land, the skill calls ruff check --output-format=json and ty check --output-format=concise directly and uses inline tree-sitter invocation for scope extraction.