review

name	review
description	Review a diff, branch, PR, or work-in-progress change against the requested spec, repo standards, architecture, and likely regressions. Use before committing non-trivial work.

Uses scratch working memory.

Review

Purpose: answer whether the diff matches the spec, standards, architecture, and project intent.

HARD CONSTRAINT — NEVER VIOLATE

NEVER run git add, git commit, git push, git stash, or any mutating git command. NEVER write, modify, or delete any application source file. This skill is read-only. If you find issues, report them as findings. Do NOT fix them. Violation of this rule is a critical failure.

Review only. Do not patch application source. As architect profile, edits are limited to Markdown, .scratch/, and docs/.

1. Identify target

Use the narrowest target that fits the request:

• User-provided base ref, PR, issue, files, or review focus.
• Staged diff when staged changes exist.
• Unstaged diff when unstaged changes exist.
• Branch diff against the likely base (main, master, or merge-base) when asked to review a branch.
• Specific files/specs/PRDs when provided.

If the target is unclear, ask one short question via AskUserQuestion and stop.

2. Read needed context only

Start with:

• git status --short via Bash
• git diff --stat via Bash
• git diff --cached --stat via Bash when staged changes exist

Then read targeted diffs only:

• git diff -- <file> via Bash
• git diff --cached -- <file> via Bash
• git diff <base>...HEAD -- <file> via Bash

Read relevant specs, issues, PRDs, standards, docs, ADRs, security notes, or project conventions only when they affect the changed area or the user requested that axis.

3. Review axes (multi-pass with working memory)

Initialize session: .scratch/reviews/<YYYY-MM-DD>/review-<slug>/

Write <session-dir>/session.md with review target, base ref, scope.

Pass 1: Standards axis

Analyze and write <session-dir>/standards.md:

• style
• architecture
• test quality
• maintainability
• security
• project conventions

Pass 2: Spec axis

Read <session-dir>/standards.md for context.

Analyze and write <session-dir>/spec.md:

• did it solve the requested problem?
• did it change public behavior unexpectedly?
• did it miss edge cases?
• did it violate PRD, issue, or user intent?

Cross-reference standards findings where relevant.

Pass 3: Security/Risk axis

Read <session-dir>/standards.md and <session-dir>/spec.md.

Analyze and write <session-dir>/security.md:

• does the change touch auth, payments, PII, session data, or external API contracts?
• does it introduce new dependencies or entitlements?
• are there error paths that could leak information?
• is there a regression path that would be hard to detect?
• does the change affect audit logs or compliance obligations?

For every Security/Risk finding, include severity and mitigation. Cross-reference previous passes.

Omit this axis when the change clearly cannot affect security (copy changes, comment fixes, test-only additions, docs-only updates).

4. Findings

Order findings by severity:

• Blocker
• High
• Medium
• Low
• Nit

For every finding include:

• file/path
• line or symbol when possible
• problem
• why it matters
• suggested fix

Prefer concrete findings over commentary. If no findings exist for a severity, omit that severity.

5. Result

End with exactly one result line:

• Review result: approve
• Review result: approve with nits
• Review result: changes requested
• Review result: blocked

6. Synthesize and complete

Read all angle files from <session-dir>/ (standards.md, spec.md, security.md if present).

Write <session-dir>/synthesis.md with:

• Summary of each axis
• Cross-cutting findings (issues spanning multiple axes)
• Prioritized findings by severity
• Result line: approve / approve with nits / changes requested / blocked

COMPLETION PROTOCOL: Your final text message is your return value. Output this summary, then STOP — do not call any more tools.

• <session-dir>/synthesis.md path
• brief result line (approve / approve with nits / changes requested / blocked)
• recommended next command

Recommended next command

If fixes are needed, recommend one next command only:

• small fix -> /zoo-tweak
• behavior fix -> /zoo-tdd
• unknown cause -> /zoo-fix
• design issue -> /zoo-refactor
• ready for evidence -> /zoo-verify

Do not auto-launch any follow-up command.