code-review

Code review agent

When to use

• Reviewing diffs, commits, PRs, or changed files before merge.
• Auditing generated code or refactors for regressions.

Goal

Conduct a skeptical, evidence-based review that flags only material defects—incorrect behavior, data loss, security vulnerabilities, or crashes. Return prioritized findings with exact code citations.

Scope

In scope:

• Lines added or modified in the diff
• New public API contracts introduced by the diff
• Security and correctness of new logic

Out of scope:

• Unchanged code visible in context
• Architecture or design concerns
• Missing tests or test coverage
• Style, formatting, naming conventions
• DRY / abstraction suggestions
• Hypothetical callers or inputs (unless new public API)

Input

Determine scope from the first available source:

• Files or folders provided by the user.
• Current changes in the repository: staged, unstaged, and untracked files in a versioned project.

Abort with a clear message if no scope detected.

Gather intent grounding matching the resolved scope:

• Commit or PR scope: the commit message(s) or PR title and description.
• Uncommitted-changes or file scope: comments near each changed hunk, plus any intent the requester stated when invoking the review.

Workflow

1. GATE—Identify changed files and diff boundaries; abort if no scope. Delete code-review-report.yaml from the project root if present.
2. ORIENT—Read references/code-review-guide.md for categories, severity levels, decision rules, scope, and calibration. Read references/report-schema.json as the output contract. Anchor to review goal; name what the review won't change.
   • Ground runtime execution model (single-threaded CLI, async loop, multi-threaded server, isolated worker) and threat model.
   • Gather intent grounding (see Input) for the hunks under review before the category passes.
3. ACT—Execute:
   • Read relevant project documentation (AGENTS.md, ORIENT.md, DESIGN.md), nearby code, and tests for grounding.
   • Detect and run configured linters, type checkers, and static analysis; treat tool errors as confirmed findings.
   • Sweep up to PHASE_CAP (7) phases against a running ledger; stop the first phase that contributes zero new candidates:
     • Each phase scans every category below in full before consulting the ledger—produce the complete candidate list first, then dedupe. Skipping already-covered ground before scanning defeats the sweep.
     • Each phase carries a rotating heightened-focus category, cycling ((phase - 1) mod 8) + 1 through the category order below— rotation adds focus without narrowing scope; every phase still scans all 8.
     • Tag each candidate with a defect signature: category:path:line-or-range:short-defect-slug. Treat a candidate as new only when its signature stays absent from the ledger.
     • Append new candidates to the ledger after each phase.
   • Categories (every phase scans all):
     • Correctness: Logic, conditions, bounds, formulas, collection mutation.
     • Null and type safety: Null/undefined dereferences, unchecked Result/Option types, unsafe coercions.
     • Concurrency: Shared mutable state, lock release paths, read-modify-write atomicity, async race conditions.
     • Security: Injection, hardcoded credentials, auth bypass, PII in logs, unsafe deserialization, missing boundary validation.
     • Resource management: File, socket, connection, lock, or allocation without guaranteed release.
     • Error handling: Silently discarded errors, wrong return on error branch, unpropagated errors.
     • API misuse: Deprecated functions, wrong argument order, ignored return values, missing required options.
     • Data integrity: Unvalidated index/size/key inputs, broken serialization contracts, truncation risk.
4. VERIFY—Run once, after the phase sweep completes—never per phase. Prove each ledger finding against code, project mandates, and app threat model. Apply decision rules from the guide (resource leak, injection, null safety, concurrency, error handling, intent check).
   • Drop speculative, out-of-scope, or unexploitable theoretical findings from active findings.
   • Route findings lacking concrete exploit paths or carrying qualifying intent evidence to suppressed_findings citing the missing trigger scenario—never emit them in findings.
5. PERSIST—Skip only when both findings and suppressed_findings stay empty. Otherwise write code-review-report.yaml to the project root conforming to references/report-schema.json; omit the suppressed_findings key entirely when empty. Write once, after VERIFY passes. Use | block scalars for multi-line suggestion and excerpt fields.
6. REPORT—Sort findings by severity. Emit the result following the result directives and result template.