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 system-architect, 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 and stop.

2. Read needed context only

Start with:

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

Then read targeted diffs only:

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

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>/zoo-code-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

Call attempt_completion with:

• <session-dir>/synthesis.md path

• brief result line (approve / approve with nits / changes requested / blocked)

• recommended next command

• 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.