diff-review

Diff Review

Find defects in one exact change that would justify altering it, with evidence the author can reproduce; repository-review owns whole-repository audits and plan-review owns plans.

Workflow

1. Resolve the target: Read the request, issue, spec, and change description; record base, head, and whether the candidate is a dirty tree, local commit, or remote pull-request head. Preserve staged, unstaged, and untracked work.
2. Inventory the delta: Inspect changed files, generated artifacts, dependency or schema changes, and the nearby code that holds the invariants; never review the diff in isolation.
3. Read tests first: Determine what behavior the candidate claims, whether the tests can fail for that defect class, and which requirements stay unproved.
4. Trace intended versus implemented: Map permissions, user journeys, data rules, failure semantics, and operational promises to concrete code paths and tests.
5. Review by risk: Weigh correctness, data integrity, authorization, input boundaries, concurrency, resource lifecycle, error propagation, compatibility, migration, performance, observability, and rollback in proportion to the change.
6. Classify scope: Compare every changed dependency, config, public API, generated artifact, and unrelated-looking hunk with the stated contract and its real call or build path.
   • Classify it as keep (necessary and connected), split (independently valuable or unrelated), or justify (real but non-obvious coupling).
   • Path names alone do not prove scope creep; never stage, revert, discard, or rewrite the candidate because a detector labels a path unrelated.
7. Verify each finding: Reproduce it by code tracing, a focused test, or a safe temporary experiment, and quote the file and line that make it real.
8. Run proportional checks: Start with focused tests and static analysis, and record which candidate each result covers.
9. Gate when proportionate: Run the full gate (mise run all); if the tree carries unrelated changes and the gate write-formats, run it in a temporary git worktree or fall back to mise run check and mise run test (see mise).
10. Calibrate: Discard preferences and speculation; rank what remains by user impact, exploitability, data loss, regression likelihood, and confidence. Do not manufacture findings to make the review look useful.
11. Report: Lead with findings ordered by severity, or say there are none and list test and proof gaps; end with the target identity, checks run, and residual risks. Other review skills reuse this scale:
    • P0: immediate security breach, irreversible data loss, or broad outage risk.
    • P1: likely correctness, security, or availability defect that should block merge.
    • P2: material edge-case, maintainability, performance, or test defect worth fixing before or soon after merge.
    • P3: minor issue, reported only when the user asked for an exhaustive review.