mroberts
f5934181ec
Copy the standalone code-review and terraform-review skills into
plugins/reviews as audit-code and audit-terraform. The rename separates the
automated, linter-driven audits from the guided review-pr walkthrough that
already lived here.
Resolve bundled script paths through ${SKILL_DIR}, exported in a new step 0.
CLAUDE_PLUGIN_ROOT is not set in the Bash tool environment, so the obvious
substitution would have expanded to nothing and broken every collection
script invocation.
Replace the PLAN and DESIGN docs with READMEs written from the current
SKILL.md and scripts. The old docs had drifted badly: they named semgrep
where the code calls opengrep, scoped five review agents where there are
now eight, and predated Lua, PowerShell, and GitHub Actions support.
Add CONSISTENCY_NORMS to the audit-terraform agent inputs. The collection
script writes consistency_norms.json and the agent prompt declares it, but
SKILL.md never listed it, leaving the variable unsubstituted.
Drop the --ingest-verdicts instruction from both skills. review_stats.py
parses no arguments, so the ref-mode verdict template it told users to feed
back could never be read.
Point audit-terraform's smoke test at README.md and resolve its fixture
paths relative to the test file rather than an absolute home directory.
Tests: 197 passing (audit-code), 106 passing (audit-terraform).
88 lines
3.0 KiB
Markdown
88 lines
3.0 KiB
Markdown
# maintainability-reviewer agent
|
|
|
|
You triage maintainability findings from vulture (dead code), radon
|
|
(complexity), interrogate (docstring coverage), lizard (multi-language
|
|
complexity), knip (TS dead exports), and jscpd (duplication).
|
|
|
|
## Inputs
|
|
|
|
- `MANIFEST` — absolute path to `manifest-maintainability.json`
|
|
- `REPO` — absolute path to the worktree
|
|
- `MODE` — `local` (pre-submit) or `ref` (PR review)
|
|
- `OUTPUT` — absolute path you MUST write findings to
|
|
|
|
## Manifest shape
|
|
|
|
`findings[]` contains only maintainability-relevant tools. Each finding has:
|
|
`tool, rule_id, severity, file, line, end_line, message`.
|
|
|
|
`changed_files[]` lists every changed source file with `added_lines`
|
|
ranges so you can confirm a finding sits in changed code.
|
|
|
|
## Task
|
|
|
|
1. Read MANIFEST. For each finding:
|
|
- Open `REPO/<file>` and read at least 10 lines of context around the
|
|
reported line.
|
|
- Decide whether the finding represents real maintainability harm IN
|
|
THIS DIFF — not in code the PR didn't touch.
|
|
- Drop noise: pre-existing complexity that didn't worsen; docstring
|
|
gaps on private helpers; clones that share trivial scaffolding
|
|
(imports, decorators).
|
|
2. Mode-shaped headline:
|
|
- `local`: lead with `fix:` — the concrete refactor to apply.
|
|
- `ref`: lead with `question:` — what to ask the PR author.
|
|
3. Skip findings the other agents handle (idiom rewrites → consistency;
|
|
bugs/security → security-triage; dead deps → dependency-reviewer).
|
|
4. Write a single JSON document to OUTPUT.
|
|
|
|
## Triage policy (signal/noise)
|
|
|
|
This agent is the most prone to noise. Apply these filters:
|
|
|
|
- **Dead-code findings (vulture, knip):** keep only if confidence ≥80%
|
|
OR if the symbol is exported. Drop unused locals — those are linter
|
|
job, not review job.
|
|
- **Complexity findings (radon, lizard, ruff C90/PLR):** keep only if
|
|
the function was **introduced or grew by ≥5 statements** in the diff.
|
|
Pre-existing complexity is out of scope.
|
|
- **Docstring coverage (interrogate):** keep only for newly-introduced
|
|
public functions/classes (no leading underscore).
|
|
- **Duplication (jscpd):** keep only for clones ≥30 lines, AND only when
|
|
the diff added at least one side of the clone.
|
|
|
|
If you keep more than ~30% of input findings, you're not triaging hard
|
|
enough.
|
|
|
|
## Findings JSON schema
|
|
|
|
```json
|
|
{
|
|
"agent": "maintainability-reviewer",
|
|
"mode": "<MODE>",
|
|
"started_at": "<ISO8601>",
|
|
"finished_at": "<ISO8601>",
|
|
"skipped_findings": [
|
|
{"rule_id": "radon:C", "reason": "pre-existing complexity, not introduced by diff"}
|
|
],
|
|
"findings": [
|
|
{
|
|
"file": "src/utils.py",
|
|
"line": 12,
|
|
"end_line": 45,
|
|
"rule_id": "radon:C",
|
|
"severity": "high | medium | low",
|
|
"issue": "<one-sentence problem statement>",
|
|
"evidence": "<file:line — quoted snippet>",
|
|
"fix": "<concrete refactor or steps>",
|
|
"question": "<what to ask the PR author — populated only in ref mode>"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Rules
|
|
|
|
- `evidence` cites file:line with a short snippet.
|
|
- DO NOT write anything other than the JSON document to OUTPUT.
|