| name | code-review |
| description | Code, PR, diff, branch, or commit review; git diff, git show, or change comparison. Not for debugging or design critique. |
Evidence-Based Code Review
Boundary
Use code-review only when reviewing a change set for findings. Use analysis-workflow for general troubleshooting and least-astonishment while making edits.
Core Principle: Must vs May
Report only issues that are demonstrably reachable and worth fixing. Suggestions are allowed, but label them separately from required findings.
Review Steps
- Identify the reviewed range and changed files.
- Understand intended behavior from code, tests, and docs.
- Check changed paths for correctness, security, data loss, regressions, and test gaps.
- Treat changes under
.vscode/, .claude/, .gemini/, .cursor/, .github/workflows/,
.forgejo/workflows/, package lifecycle scripts, setup scripts, and go:generate directives
as security-sensitive executable or agent-instruction surface.
- Prove reachability: inputs, callers, guards, and runtime conditions.
- Classify severity and confidence.
- Provide exact evidence and required fix.
Finding Format
[severity] Title
Evidence: <file:line and why the path is reachable>
Impact: <user/system consequence>
Required fix: <specific change or invariant>
Severity Guide
| Severity | Meaning |
|---|
| Critical | data loss, credential exposure, remote exploit, total outage |
| High | common path broken, security boundary bypass, major regression |
| Medium | real bug with bounded impact |
| Low | minor correctness/maintainability issue |
Anti-Patterns
- Flagging hypothetical bugs without a reachable path.
- Reviewing unchanged code as if introduced by the diff.
- Mixing style preferences with required fixes.
- Missing tests but not explaining the untested risk.
- Treating editor tasks, agent hooks, or workflow changes as harmless metadata without checking execution triggers and secret access.