independent-review

Files (3)

• SKILL.md
• design-bindings.md
• review.py

SKILL.md (first lines)

> **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 design-fidelity eval's frozen
  verdict (selected static native overall policy, or unselected historical
  scalar 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:

```text
[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:

```bash
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:

```bash
PROMPT=$(python3 "${CLAUDE_PLUGIN_ROOT}/skills/independent-review/review.py" \
  pr-review \
  "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 pr-review)
```

From ramboz/jig, MIT.

More from ramboz/jig