Review

Why this workflow exists

A review is only as good as two things: whether the target is pinned, and whether every finding carries evidence. Review freezes the comparison point first — a diff, a branch merge-base, or uncommitted work — then checks eight independent axes one by one. Every finding cites its location, its evidence, and the smallest credible correction. Finding a defect never grants permission to fix it.

How it runs, stage by stage

Every rule below is taken from the workflow definition in the source repository — this is what the agent is actually told to do.

1. 01

   Define the comparison

   Pin the target first — a moving target cannot be reviewed.

   • Use the supplied fixed point when one is present.
   • For a branch comparison, resolve the merge base and inspect the commits plus the three-dot diff.
   • For current uncommitted work, inspect staged, unstaged, and relevant untracked files against HEAD.
   • Fail clearly on a bad reference or empty scope instead of reviewing the wrong change.
2. 02

   Recover intent

   Learn what the change was supposed to do before judging what it does.

   • Read in priority order: your current review request, then project instructions, then the originating requirement, issue, design, or acceptance criteria, then relevant tests and documentation.
   • If no specification exists, state that the review can assess correctness risk and maintainability but not complete requirement fidelity.
3. 03

   Review eight independent axes

   Each axis is checked on its own — never blurred into a general impression.

   • Requirements: missing, partial, incorrect, or unrequested behavior.
   • Correctness: edge cases, failure handling, concurrency, state, and call-site impact.
   • Safety: permissions, trust boundaries, data integrity, destructive effects, compatibility, and accessibility.
   • Design: ownership, semantic reuse, false deduplication, abstraction cost, and unnecessary dependencies.
   • Readability: explicit flow and effects, meaningful names, local reasoning, debuggability, and unjustified novelty.
   • Tests: whether tests exercise stable public behavior and can actually detect the defect.
   • Documentation: stale or contradictory facts, and requirements rewritten to fit the implementation.
   • Scope: unrelated edits, temporary diagnostics, generated artifacts, and unauthorized operations.
   • Do not flag preferences already enforced by tooling, or purely subjective alternatives with no maintenance impact.
4. 04

   Report findings

   Impact first, evidence always, and not a single file edited.

   • Order findings by impact.
   • Each finding includes severity, file and precise location, evidence from the diff plus the relevant requirement or invariant, user-visible or maintenance impact, and the smallest credible correction direction.
   • Do not hide important findings inside a summary.
   • If no material findings exist, say so and note any verification gap.
   • Do not edit files, commit, or push at any point.

Rules that cannot be bypassed

A real invocation

What the conversation actually looks like, from the token you send to the evidence you get back.

1. Agent

   Resolves the scope: staged, unstaged, and relevant untracked files compared against HEAD.

2. Agent

   Reads docs/access-policy.md and the project instructions to recover what the change was supposed to do.

3. Agent

   Walks the eight axes one at a time, flagging a permission check that runs after the mutation as the highest-impact finding.

4. Agent

   Reports findings ordered by severity — each with file, line, diff evidence, impact, and the smallest credible correction — and edits nothing.

When to use it

• You want an independent check before merging.
• The target is a diff, a branch, a pull request, or uncommitted work.
• You want a findings report rather than silent edits.
• You need severity-ordered findings you can hand to whoever will fix them.

When to reach for something else

Questions