/independent-review

name: independent-review
description: >
  Build the standardized prompt for a fresh reviewer subagent that evaluates
  implemented work against its spec without access to the implementation
  conversation. Use after an implementer subagent completes a spec slice (when
  the slice is ready for REVIEWED), or after a deviation log is written (for
  reconciliation review). Do not use for ad-hoc code review unrelated to a
  spec, or for reviewing a spec's authorship (that's the READY_FOR_REVIEW step
  in spec-workflow).
user-invocable: true

> **Working posture ([ADR-0056](../../docs/decisions/adr-0056-adversarial-register-quarantine.md)).** > Adversarial review is a *named, bounded operation.* The skeptical, > flaw-hunting register this skill builds belongs *inside* the review passes — > they run in isolated reviewer subagents whose context is discarded. Outside a > review, default to collaborative and solution-forward; don't carry the > adversarial stance into ordinary conversation.

> Spec 004 promoted this skill from stub to active. The prompt is constructed > by `review.py`; Claude owns the Task invocation.

What this skill does

Constructs the standardized reviewer-subagent prompt and tells Claude when / how to spawn the Task. The skill has four modes, matching the review passes every slice may run:

• **Implementation review** — after the implementer writes the deliverable to

disk. The reviewer evaluates each acceptance criterion against the actual files; returns `pass | fail | needs-changes`. This is the **compliance pass** in spec-workflow's multi-pass flow.

• **Pr-review (craft pass)** — slice 031-01. After the compliance pass

returns, the orchestrator runs a craft-pass review that produces the four-bucket output (scope / blockers / nits / strengths) the `jig:pr-review` skill emits, wrapped in the same verdict envelope as the compliance pass. SPECIFIC ISSUES entries are tagged `[blocker]` / `[nit]` / `[strength]` so the workflow can decide what blocks the REVIEWED transition vs. what becomes a reconciliation-log entry.

• **Arch-review (architecture pass — on-demand)** — slice 031-02. After

the craft pass returns, the orchestrator queries the slice's `arch_review:` frontmatter flag via `workflow.py arch-review-needed`; when `true`, it runs an arch pass producing the four-bucket output (summary / strengths / concerns / open questions) the `jig:arch-review` skill emits, in the same verdict envelope. Slice authors set `arch_review: true` in the slice's frontmatter when the slice changes module boundaries, public contracts, or architecture-shaped concerns; the slice template at `templates/docs/specs/slice-template.md` ships the field commented out as a discoverability nudge.

• **Design-review (attest-only pass — on-demand)** — slice 071-01 /

ADR-0022. After the craft (+ arch) passes, the orchestrator queries the slice's `design_review:` flag via `workflow.py design-review-needed`; when `true`, it runs an **attest-only** pass: the read-only reviewer attests an external, non-deterministic design-fidelity eval's frozen verdict (e.g. servo's `.servo/design-eval/` composite ≥ its own threshold, non-stale, `env_error` ≠ pass) and records pass/fail — it never re-runs or re-derives the score (servo runs/scores, jig attests). Gates REVIEWED like arch. Authors set `design_review: true` when the slice ships UI gated by an external design-fidelity eval — and the slice body must point at **where the eval evidence lives** (the frozen config + threshold and the results ledger), since the reviewer can only attest a verdict it can locate; with no pointer it has nothing to read and records a `fail`.

• **Reconciliation review** — after the deviation log is written. The

reviewer verifies the doc changes match reality; does NOT re-review the ACs.

`review.py` builds the prompt text; `agents/reviewer.md` defines the agent's tool restrictions and persistent system rules.

How to use

Task telemetry tags

When you feed a `review.py` prompt to the `Task` tool, prefix the prompt with the compact attribution tags that `jig-telemetry.sh` records:

[jig:phase=<phase>] [jig:spec=NNN] [jig:slice=NNN-NN]

<review.py prompt body>

Use `compliance` for `review.py implementation`, `craft` for `pr-review`, `arch` for `arch-review`, `code-health` for `code-health`, `frame-critique` for frame critique, and `reconciliation` for reconciliation review. These tags make later token reports price the workflow phase, not just the subagent type.

> **Always pass `spec.md`, in every recipe below.** The helper resolves which > file actually holds the named slice — a sibling `slice-NN-<short>.md` under > the file-per-slice layout, or the `## Slice` section of `spec.md` under the > embedded one — and points the reviewer at that file, with `spec.md` trailing > as context. Do not hand-substitute the slice path (bug 019).

Implementation review

After the implementer has written the deliverable to disk:

PROMPT=$(python3 "${CLAUDE_PLUGIN_ROOT}/skills/independent-review/review.py" \
  implementation \
  "docs/specs/NNN-<slug>/spec.md" \
  "<slice-fragment>" \
  "<deliverable-path-1>" "<deliverable-path-2>" ...)
SUBAGENT=$(python3 "${CLAUDE_PLUGIN_ROOT}/skills/independent-review/review.py" \
  subagent-type implementation)

Then feed `[jig:phase=compliance] [jig:spec=NNN] [jig:slice=NNN-NN]\n\n$PROMPT` to the `Task` tool with `subagent_type: "$SUBAGENT"`. The helper resolves `$SUBAGENT` deterministically — `reviewer` when jig is installed as a plugin (the real filesystem-based agent is reachable), `general-purpose` when running from source. Wait for the verdict. Address any `fail`/`needs-changes` findings; rerun the helper + Task as needed until `pass`.

Pr-review (craft pass — slice 031-01)

After the compliance pass returns `pass`, run the craft pass:

PROMPT=$(python3 "${CLAUDE_PLUGIN_ROOT}/skills/independent-review/