Ad Review

/ad-review

Implements WORKFLOW §10 (Reviewer With Fresh Context). The current session is biased about the code it produced — the same reasoning that wrote it defends it. This skill assembles two clean handoffs (Standards-axis, Spec-axis), delegates each to a sub-agent that starts with no history, and aggregates the findings side-by-side. The two axes are deliberately separate so a Spec pass cannot mask a Standards fail (and vice versa) — the dichotomy is borrowed from mattpocock/skills/review and bound to this kit's six-layer artifact stack.

Step 0 — Scope the review

Confirm what to review. Default scopes, in priority order:

1. User-named ref or PR (/ad-review main..HEAD, /ad-review PR#42, /ad-review <commit-sha>).
2. Current branch vs main (git diff main...HEAD).
3. Working-tree changes (git diff plus git diff --staged).

If no diff exists, stop and tell the user — there's nothing to review.

When the host exposes AskUserQuestion, use it at Step 0 to confirm the review scope as a multi-choice card (branch vs main / PR#NN / commit-sha / working-tree) instead of asking inline text. Falls back to numbered text on hosts without the primitive (Codex).

Capture the diff command once: git diff <range> (use ... three-dot for ref-vs-ref so the comparison is against the merge-base). Note the commit list with git log <range> --format=%B.

Handoff-integrity gate. Compute the commit count: git rev-list --count <range>. Bind it to N. The handoff header must include the literal line Range: <range> (N commits). The ## Spec slice — commit messages section must contain exactly N ### <sha> <subject> entries. If your body has fewer, you mis-bounded the range — stop and re-scope. The subagent's review signal is bounded above by handoff fidelity; a quiet count mismatch produces silently-incomplete reviews.

Step 1 — Identify Standards sources

Anything in the repo that documents how code should be written. Read what exists; do not fabricate references.

• AGENTS.md at the repo root.
• ARCHITECTURE.md at the repo root.
• GUIDELINES.md at the repo root.
• CONTEXT.md at the repo root, or CONTEXT-MAP.md plus per-context CONTEXT.mds.
• Every ADR under doc/adr/ with Status: accepted whose subject is touched by the diff. When in doubt, include rather than skip.
• CONTRIBUTING.md if present.
• Machine-enforced standards (.editorconfig, eslint.config.*, biome.json, prettier.config.*, tsconfig.json) — note their presence, but instruct the Standards sub-agent to skip what tooling already enforces.

Step 2 — Identify the Spec source

In this order, take the first that resolves:

1. Task references in the diff or recent commit messages (Task NNNN, 0NNN-, Closes task-0042) → read the file's Acceptance Criteria and Plan sections.
2. An originating spec under doc/specs/ whose filename matches the branch name or the dominant feature touched by the diff.
3. A parent PRD under doc/product/ referenced by the spec.
4. Issue references in commit messages (#123, Closes #45) — fetch via gh issue view if the kit has gh available.

If nothing resolves, mark the Spec axis as no spec source provided and the Spec sub-agent will skip with a one-line note rather than fabricate findings.

Step 3 — Build two axis-bounded handoffs

Each sub-agent will receive only the slice for its axis. Do not paste the Spec slice into the Standards handoff or vice versa — that's the bias the split exists to prevent.

Standards handoff (<scope>-standards.md):

=== AGENTIC-REVIEW HANDOFF — STANDARDS AXIS ===

Axis: Standards. Report only findings that violate documented standards or
introduce bugs / coupling / edge-case gaps. Skip what tooling enforces.
Skip Spec-axis findings (missing requirements, scope creep) — a separate
sub-agent covers those.

--- DIFF ---
<git diff output>

--- STANDARDS SOURCES ---
<AGENTS.md, ARCHITECTURE.md, GUIDELINES.md, CONTEXT.md / CONTEXT-MAP.md,
applicable accepted ADRs (full text), CONTRIBUTING.md if present>

--- TOOLING NOTE ---
<list of machine-enforced configs found — eslint.config.*, biome.json,
.editorconfig, tsconfig.json, etc. The sub-agent must NOT re-check what
tooling already enforces.>

=== END HANDOFF ===

Spec handoff (<scope>-spec.md):

=== AGENTIC-REVIEW HANDOFF — SPEC AXIS ===

Axis: Spec. Report only:
  (a) requirements the spec asked for that are missing or partial;
  (b) behaviour in the diff that wasn't asked for (scope creep);
  (c) requirements that look implemented but where the implementation
      looks wrong against the spec line.
Quote the spec line for each finding. Skip Standards-axis findings — a
separate sub-agent covers those.

--- DIFF ---
<git diff output>

--- SPEC SOURCES ---
<task file Acceptance Criteria + Plan, originating spec (full text),
parent PRD (full text), recent commit messages for the range, originating
issue body if fetched>

=== END HANDOFF ===

If Step 2 found no spec, write the Spec handoff as a single block: no spec source provided — report exactly that and stop.