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 and baseline-tracker agents, 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, check, stats, explain, configure), AST-scoped findings, in-band .toolkit.local.md suppression-list reading, and severity-aware payload assembly.

Purpose

Triage diagnostic output from the project's rust language server and CLI checkers (clippy and rustc, exposed through cargo clippy and cargo check). Categorize each finding by severity, scope it to its containing function, impl block, or module via tree-sitter, suggest a fix, and route the finding through the noise-suppression layer so already-suppressed lint groups are filtered out before the user sees them.

This skill is the single entry point for every diagnostic flavor the rust-toolkit exposes. Invoke it directly from the user-facing per-pass skills (/check, /clippy, /stats, /explain, /configure) by passing a pass: argument. Auto-activate it whenever clippy or rustc output appears in a recent tool result, even when the user did not explicitly ask for triage. The same body satisfies three roles — auto-activation surface, slash-command implementation, and shared procedure carrier — so all diagnostic UX in the rust-toolkit converges on one canonical workflow.

When to Use

• The user asks to "review diagnostics", "check code quality", "show clippy warnings", "show lint violations", or "explain this clippy lint".
• A recent tool result contains clippy or rustc output (lines beginning with warning:, error:, --> <file>:<line>:<col>, or JSON shaped from --message-format=json) and the user has not yet acknowledged it.
• A per-pass skill (/check, /clippy, /stats, /explain, /configure) routes here with an explicit pass: argument.
• The /watch primitive's threshold rule fires and dispatches a triage pass before deciding whether to spawn the diagnostic-fixer agent.
• The noise-curator agent reports back that a previously suppressed lint may be removable; load the curation reference to walk the user through the decision.

When NOT to Use

• The user asks to apply fixes automatically rather than review them — dispatch the diagnostic-fixer agent instead, which wraps fix application in a verification loop.
• The user asks to manage the suppression policy in bulk (/curate-suppression) — the noise-curator agent owns that flow; this skill only reviews single curation prompts on demand.
• The user asks to capture or compare diagnostic baselines — defer to the /baseline skill and the baseline-tracker agent.
• A non-rust language is the source of the diagnostics — defer to that language's diagnostic-review skill (e.g., python-toolkit:diagnostic-review).

Usage

Invoke this skill directly, or call it from a per-pass skill by passing pass: as a structured argument. Each pass selects a different vocabulary against the same triage backbone:

• pass: lint — run cargo clippy --message-format=json --all-targets -- -W clippy::all and triage every emitted finding. Suppress lint groups disabled in .toolkit.local.md. Surface a severity-bucketed table; for each non-suppressed finding, attach the AST-scoped containing item.
• pass: check — run cargo check --message-format=json --all-targets and triage rustc diagnostics. The rust toolchain treats cargo check as the canonical typecheck pass — there is no separate "typecheck" pass for rust because rustc-emitted errors are already type errors. Errors take precedence over warnings; the triage table sorts errors first.
• pass: stats — run the lint pass without per-finding triage; emit only category counts. Useful for dashboards, statusline cache writes, and threshold-rule evaluation. Do not load references/codes.md for this pass.
• pass: explain CODE — call cargo clippy --explain <CODE> (strip any clippy:: prefix the user supplied). Print the official explanation, the example code, the rationale, and any noise-suppression status from the project's .toolkit.local.md. Cross-reference references/codes.md for the lint group's curated one-liner.
• pass: configure — scaffold or update the project's .toolkit.local.md (suppression policy + watch thresholds) plus the clippy.toml, rustfmt.toml, and .cargo/config.toml baselines. Detect whether the project tier should be library, binary, workspace, or embedded; pick suppression defaults from references/codes.md.

When invoked without an explicit pass:, infer the pass from context. If the user pasted clippy output, default to pass: lint. If they pasted rustc errors, default to pass: check. If they asked to explain a single code, default to pass: explain CODE.

Auto-activation: when this skill detects rustc or clippy output in tool results — patterns include the lint marker clippy::<group>::<lint>, the warning prefix warning: followed by --> source-pin lines, error codes of the form error[E####]:, or any line beginning error: aborting due to previous error — surface a structured triage summary without waiting for a user prompt. Prefer brevity in the auto-activated path; do not load the full code reference unless the user follows up.

Procedure

For the full triage procedure — project-tier detection, suppression filter application, severity-aware AST scope walk, payload assembly, and output formatting — load references/procedure.md. The procedure is identical across all passes; the per-pass differences live in (a) which CLI command produces the source diagnostics and (b) which subset of the procedure runs (for example, pass: stats skips scope walking entirely).

For the diagnostic code reference — clippy lint groups (style, complexity, perf, pedantic, restriction, nursery, suspicious, correctness, cargo), the top twenty most-common individual lints with one-liners and rationale, and a pointer to cargo clippy --explain <code> for everything else — load references/codes.md. Load this file only when explaining a specific code or when the configure pass needs default suppression candidates; the file is large enough that loading it eagerly wastes context.

For the suppression-list curation flow — used when the noise-curator agent surfaces a prompt asking whether to remove a stale suppression, or when a successful diagnostic-fixer run touches a code that was in the suppression list — load references/curation.md. The curation reference encodes the user-confirmation contract: never edit .claude/<plugin>.local.md silently; always present the proposed change, the evidence (diagnostic no longer fires, or fixer succeeded cleanly), and an explicit accept/decline prompt before writing.

Output Format

Surface a structured triage in this shape, regardless of pass:

pass: lint | check | stats | explain | configure
project_tier: library | binary | workspace | embedded | unknown
totals:
  errors: N
  warnings: N
  hints: N
  suppressed: N
findings:
  - severity: error | warning | info | hint
    code: <lint-id-or-rustc-code>
    file: <relative-path>
    line: <int>
    column: <int>
    scope:
      kind: function | impl | module | line
      name: <containing-symbol-or-null>
      span: <start-line>-<end-line>
    message: <one-line>
    fix_hint: <one-line | machine-applicable | manual>
    suppression_status: active | suppressed | candidate-for-removal
notes:
  - <free-form, e.g., "ty-coverage-gap-equivalent rust shape: rustc and clippy disagree on FFI bounds">

For pass: stats, only emit pass, project_tier, and totals. For pass: explain, emit pass plus the explanation block (rendered markdown, not yaml) plus suppression status. For pass: configure, emit a yaml-shaped summary of the writes the configure pass would apply, and obtain user confirmation before writing.

Resources

• references/procedure.md — canonical triage procedure (project-tier detection, suppression filter, AST scope walk, payload assembly, output formatting). Load on every pass except stats.
• references/codes.md — clippy lint group reference with the top twenty most-common individual lints and one-liner rationale. Load on demand for explain and configure passes.
• references/curation.md — suppression-list curation flow with the user-confirmation contract. Load when the noise-curator agent surfaces a curation prompt or when a fixer run touches a suppressed code.
• scripts/parse_clippy_json.py (deferred — depends on the LSP-MCP bridge contract; tracked in chore #45) — fast deterministic parser for cargo clippy --message-format=json. Until the script lands, parse via inline jq or python invocations.
• scripts/ast_scope.py (deferred — same dependency) — tree-sitter helper extracting the containing scope for a diagnostic. Until the script lands, fall back to a fixed line-and-context window of three lines on either side of the reported location.

Invariants

Apply these invariants on every invocation, regardless of pass:

1. Suppression filter precedes scope walk. Skip the AST scope extraction for any finding that is already suppressed by .toolkit.local.md; emit it under totals.suppressed only and never expand it into the findings list.
2. Severity drives scope depth. Errors walk to module level (full file context, since type errors propagate); warnings walk to the containing function or impl block; info and hint walk only to the affected line plus two lines of context. The procedure reference encodes the rules; do not improvise.
3. No silent suppression edits. This skill never writes to .claude/<plugin>.local.md. The curation reference and the noise-curator agent are the only paths that propose suppression changes, and both require explicit user confirmation before writing.
4. Plan-mode advisory. When the session is in plan mode (per the /watch permission-mode check), do not invoke diagnostic-fixer and do not surface action prompts. Emit only the triage summary with a leading note: "plan mode — advisory only, no fixes will be applied".
5. Bounded output. When more than fifty findings would be surfaced, paginate by severity bucket; default to printing all errors plus the top ten warnings plus a summary line for the rest. Do not flood the conversation.

Notes for Auto-Activation

When this skill auto-activates from tool-result inspection (no explicit user prompt), prefer the lightest path: pass: stats if the user has not yet engaged with the diagnostic output, pass: lint once they ask a follow-up. Surface the activation explicitly — for example, "I noticed clippy output in the previous tool result; here is a structured triage" — so the user can opt out.

When the user explicitly invokes a per-pass skill, honor their choice exactly; do not second-guess the pass selection. The per-pass skills are thin wrappers that exist precisely to make the user's intent unambiguous.