reviewing-code · diff
git:20260716.29b4d22 to git:20260928.d0a85d1
36 added, 113 removed. Audit A to B.
---
- description: Use when reviewing changed code, PRs, diffs, or specific files. Finds
+ description:
+ Use when reviewing changed code, PRs, diffs, or specific files. Finds
evidence-backed defects in security, correctness, tests, reliability, performance,
maintainability, and docs. Supports quick, standard, deep, team, and external-review
- modes. NOT for repo-wide architecture review, general codebase exploration, fixing
+ modes, plus a simplify mode for over-engineering and "what can we delete" reviews. NOT for repo-wide architecture review, general codebase exploration, fixing
issues (use fixing-code), improving tests without a code review (use improving-tests),
or applying refactors (use refactoring-code).
name: reviewing-code
---
# Code Review
- Produce findings, not edits. Review only the requested diff, PR, changed files,
- or file list. If scope or diff context is missing, ask one clarifying question.
-
- ## Read first
+ Produce findings, not edits, for the requested diff, PR, changed files, or file
+ list. Read `references/severity-rubric.md` before scoring or reporting: it owns
+ the dimensions, severity, confidence, and score rules.
- Read `references/severity-rubric.md` before scoring or reporting findings.
- Load language references only for languages present in scope:
+ Load a language reference only for languages in scope:
- C#: `references/csharp.md`
- Go: `references/go.md`
- Java/Kotlin: `references/java-kotlin.md`
- Python: `references/python.md`
- Rust: `references/rust.md`
- TypeScript: `references/typescript.md`
- Web, HTML, CSS, JS, HTMX: `references/web.md`
- Unsupported language: use this skill and the severity rubric only; report reduced coverage.
-
- ## Review modes
-
- Default mode is standard unless the user asks otherwise.
-
- Quick:
-
- - Use for small, low-risk diffs.
- - Cover security and correctness only.
- - Review changed lines plus direct local context.
-
- Standard:
-
- - Use for normal reviews.
- - Cover security, correctness, and tests.
- - Review changed files plus direct callers or callees when needed to validate a finding.
-
- Deep:
-
- - Use when the user asks for deep, thorough, risk, or merge-safety review.
- - Cover all dimensions: security, correctness, tests, reliability, performance, maintainability, and docs.
- - Review changed files, relevant callers/callees, boundary inputs, and affected tests.
-
- Team:
-
- - Use only when the user asks for team, parallel, multi-agent, or multi-pass review.
- - Split by dimension or file group, then consolidate into one report.
- - Deduplicate by `file:line` plus claim. Keep the strongest severity only when evidence supports it.
- - Put unresolved disagreements under Needs review, not confirmed findings.
-
- External:
-
- - Use only when the user explicitly asks for external, Codex, second model, or second opinion.
- - Keep private code local unless the configured bridge runs locally or the user approved sharing.
- - Consolidate external output with the same severity rubric. Downgrade unsupported external claims to Needs review.
- - Report whether external review completed, was unavailable, or was skipped for privacy/tooling reasons.
-
- ## Scope resolution
-
- Use the user's named scope without asking. Otherwise choose one:
-
- - Uncommitted changes.
- - Branch compared to default branch.
- - Specific files or PR diff supplied by the user.
-
- Tool-enabled role: use the matching git or PR command consistently for the whole review.
- Read-only role: work from supplied diff, file list, and tool output. If that context is absent, ask for it instead of guessing.
-
- If there are no changes in scope, report `Nothing to review.`
-
- ## Evidence gathering
-
- For each scoped language:
-
- 1. Read the relevant language reference.
- 2. Inspect changed code and enough nearby code to validate claims.
- 3. Use supplied or runnable tooling output when available.
- 4. Use graph evidence only when it answers a review question, not as a default fishing pass.
-
- A change-history graph tool (such as GitNexus), when installed, is useful for PRs, broad diffs, public API changes, and missed caller/test coverage:
-
- - Detect changes to map changed symbols to affected flows.
- - Impact analysis for non-trivial changed symbols.
- - Context for changed boundary symbols, callers, callees, and tests.
-
- A code dependency graph tool (such as codegraph), when installed, is useful for dependency/call blast radius and high fan-in surfaces:
-
- - Check status first.
- - If fresh, use context or affected queries for changed symbols or files.
- - Stale or partial indexes are not evidence. Refresh if allowed; otherwise report the gap.
-
- ## Review dimensions
+ Other languages: use the rubric alone and report reduced coverage.
- Security, correctness, tests, reliability, performance, maintainability,
- simplicity (over-engineering), and docs. Scope and coverage checklist per
- dimension: `references/severity-rubric.md`.
+ ## Scope
- Simplify focus:
+ Use the scope the user named. Otherwise ask one question offering:
- - When the user asks for a simplification, over-engineering, or "what can we delete" review, scope to the Simplicity dimension only and emit a delete-list instead of the standard template.
- - One line per finding: `file:line — <tag> <what>. <replacement>.` Tags: `delete` (dead or speculative, nothing replaces it), `stdlib` / `native` (name the function or platform feature), `yagni` (one implementation, inline it), `shrink` (same logic, fewer lines).
- - End with `net: -N lines possible.` Nothing to cut: `Lean already. Ship.`
+ - uncommitted changes
+ - branch compared to the default branch
+ - specific files or a PR diff
- ## Finding rules
+ Use one git or PR command for the whole review. Without command access, work
+ from the supplied diff and files, and ask for them if absent. No changes in
+ scope: report `Nothing to review.`
- - Every confirmed finding needs `file:line` or quoted tool output.
- - Every confirmed finding needs severity, category, confidence, scenario, and fix.
- - No evidence, no finding.
- - Missing context becomes Needs review, not a hedged finding.
- - Do not report style or formatting already handled by project tooling unless it creates real risk.
- - Keep findings scoped. List adjacent suspicious areas as out of scope instead of expanding the review.
- - Security web research is only for public facts such as CVEs or official docs. Do not send private code or diffs to web tools.
+ ## Modes
- ## Scoring
+ Default is standard.
- If the user asks for a score, apply `references/severity-rubric.md` exactly:
+ - **Quick**: small, low-risk diffs. Security and correctness; changed lines plus direct context.
+ - **Standard**: security, correctness, and tests; follow callers or callees when a finding needs them.
+ - **Deep**: on request for a thorough, risk, or merge-safety review. All rubric dimensions, including boundary inputs and affected tests.
+ - **Team**: on request for team, parallel, or multi-pass review, or offered for a large diff. Split by dimension or file group, then merge into one report: dedupe by `file:line` plus claim, keep the higher severity only when evidence supports it, and put disagreements under Needs review.
+ - **External**: only when the user explicitly asks for an external, second-model, or second-opinion review. Keep private code local unless the bridge runs locally or the user approved sharing. Rate external output with the same rubric; claims you cannot verify go to Needs review. Report whether it completed, was unavailable, or was skipped and why.
+ - **Simplify**: on request for an over-engineering or "what can we delete" review. Simplicity dimension only. Instead of the Output template, one line per finding: `file:line — <tag> <what>. <replacement>.`, with tags `delete`, `stdlib`/`native` (name the replacement), `yagni`, `shrink`. End with `net: -N lines possible.` or `Lean already. Ship.`
- 1. Assign severity and confidence for each finding.
- 2. Apply caps first.
- 3. Apply deductions.
- 4. State score confidence: high, medium, or low.
- 5. If review coverage is partial, show the cap reason.
+ ## Evidence
- Do not invent precision. Use one decimal only when arithmetic needs it.
+ - Read enough surrounding code to prove each claim. Run the project's checks when you can; a failing check in scope is evidence.
+ - If a code-graph tool (GitNexus, codegraph) is installed, use it for caller, impact, and test-coverage questions on broad or public-API changes; a stale index is a coverage gap, not evidence.
+ - Web research is for public facts only (CVEs, official docs). Never send private code or diffs to web tools.
+ - Skip style that project tooling already enforces. List suspicious code outside scope as out of scope instead of widening the review.
+ - Review generated or vendored files only when source generation is in scope.
## Output
```markdown
## Code Review Summary
Scope: <description>
Depth: quick | standard | deep | team | external
Languages: <list>
Coverage: complete | partial — <reason>
- Graph evidence: none | <graph tool(s) used> — <freshness/gaps>
+ Graph evidence: none | <tool> — <freshness/gaps>
External review: not requested | completed | unavailable | skipped — <reason>
Score: <N/10 if requested> — confidence <high|medium|low>
### Critical
- `file:line` — <category>, confidence <level>. <issue> Scenario: <how it fails>. Fix: <concrete fix>.
### Warnings
- `file:line` — <category>, confidence <level>. <issue> Scenario: <how it fails>. Fix: <concrete fix>.
### Suggestions
- `file:line` — <category>, confidence <level>. <improvement>. Fix: <concrete fix>.
### Needs review
- `file:line or tool/context gap` — <missing context and why it matters>.
### Summary
- <2-3 sentences with merge risk and next actions. Say "No confirmed findings" when clean.>
+ <2-3 sentences: merge risk and next actions, or "No confirmed findings".>
```
- Omit empty severity sections except Needs review when it explains partial coverage.
+ Omit empty sections, except Needs review when it explains partial coverage.
- ## Edge cases
+ ## Platform additions
- - Missing diff or file list in read-only mode: ask for it.
- - Tool unavailable: report the gap and continue with source review.
- - Tests missing for changed behavior: report under tests with the missing behavior named.
- - Large scope: review requested scope first; recommend deep/team mode for more coverage.
- - Generated or vendored files: review only if the change is direct and source generation is in scope.
+ No target-specific additions.
+