code-review

Code Review

Overview

Catch issues before they cascade. A review pass has three jobs:

1. Confirm the captured rules pass. Run validate_diff against the changes; rule violations are non-negotiable Critical issues.
2. Read the diff with fresh eyes. Look for dead code, missing tests, half-finished implementations, error-handling gaps, security smells, and assumptions that aren't justified by the change.
3. Verify intent matches outcome. The diff should accomplish exactly what the task or PR description claims — no more, no less.

Output is a structured report the user can act on.

When to call

Mandatory:

• After finishing a task in a multi-task plan, before moving to the next task.
• Before telling the user a feature is done.
• Before commit / before merge to main.

Optional but valuable:

• When stuck — fresh perspective on the diff often surfaces the issue.
• After fixing a complex bug, before claiming it's fixed.
• Before a refactor — baseline check on what currently works.

Skip when:

• Single-character typo fix.
• The user is the one reviewing in real time and explicitly didn't ask.

Procedure

Step 1: Define the scope

Identify exactly what's being reviewed:

# For uncommitted changes:
git status
git diff --stat

# For a branch:
BASE=$(git merge-base origin/main HEAD)
git diff --stat $BASE..HEAD

# For a single commit:
git show --stat <sha>

Capture: list of changed files, total lines added/removed, the task description or PR title.

Step 2: Run rule validation

Call validate_diff with the changed files and their final contents. Any violation here is a Critical issue — the change is conceptually wrong by the team's own captured rules.

validate_diff({
  changes: [
    { path: "<repo-relative>", content: "<full final content>" },
    ...
  ]
})

If the diff is committed already, run validate_diff with the on-disk content (still works — the engine treats it as a virtual graph).

Step 3: Read the diff for non-rule issues