Review Harness

---
name: review-harness
description: >-
  Periodic multi-angle improvement review of the reference. Always fans out all five
  read-only research agents in parallel — maintainer tooling, documentation, runtime cost,
  source duplication, consumer surface — so cross-angle tension informs the synthesis.
  Every agent carries the challenge charter: question the design against the README's
  stated philosophy, recommend removals that pay for themselves. Judges findings by the
  resilience-first doctrine; a settled ADR decision is rebuttable with a new argument,
  never silently suppressed. "/review-harness challenge" drops the ADR anchoring from
  the agent prompts for a zero-based outside look. Adversarially verifies structural findings and delivers
  one prioritized report. Assessment only — never edits. Complements /audit-harness,
  which gates defects against the current bar. Root-only (Claude Code).
compatibility:
  - claude-code
metadata:
  version: "1.0"
  author: team
---

# Review Harness (improvement scan)

Find opportunities to raise the bar on maintainability, clarity, cost, and resilience — and judge them consistently. `/audit-harness` answers "does the repo meet its current bar" with one verdict; this skill answers "where could the bar move" with one prioritized report. The default run is doctrine-anchored; the `challenge` arg (§ Challenge mode) trades that anchor for a zero-based outside look.

## Challenge charter

Every step 3 research-agent prompt carries this charter, verbatim; the step 5 skeptics never receive it — their mandate is refutation:

> Challenge assumptions rather than preserving the current design. Judge the repository against the philosophy and goals its README and `docs/force-multiplier.md` state. Look for ways to improve software quality, agent reliability, developer experience, and long-term maintainability. Reduce complexity, ambiguity, token usage, and execution time without sacrificing outcomes. Recommend removing or consolidating guidance that does not pay for itself. Prioritize high-impact improvements over minor editorial feedback.

At synthesis, the Invariants and the do-not-cut list outrank the charter.

## Invariants

Output quality and pipeline autonomy are non-negotiable. Never propose a change that weakens a behavioral guarantee or adds a human touchpoint to save cost. Run the review end-to-end without pausing for confirmation; the report is the deliverable. Never edit repository files during the review run. Follow-up work — including step 7's disposition records — lands through the maintainer loop in the root `CLAUDE.md`, after the user dispositions the findings.

## Procedure

1. **Survey (cheap, run at root).** Run `harness/review-survey.sh` — it emits the measurements the agents anchor on: word sizes per doc surface, 6-month churn per file, cross-stack overlap line counts, and the commits since the last `v*` tag. One script, one set of numbers — every agent prompt quotes the same survey.
2. **Read the ADRs.** Scan the `docs/adr/README.md` index for decisions bearing on the angles, starting with the resilience-first doctrine and any ADR a prior review produced. A settled decision is a rebuttable presumption, not a gag order. A finding may challenge one only by engaging its recorded rationale — stating what changed, or what the rationale missed. Synthesis suppresses a challenge only for failing that bar: no new argument, including a restated § Options Considered entry. Step 6 names every suppressed challenge — suppression is never silent.
3. **Fan out all five angles in parallel** — one read-only `general-purpose` agent each, dispatched in a single message. Never scope down to fewer angles to save tokens; the cross-angle tension is the value. Each prompt carries: the angle charter (table below), the challenge charter, the survey numbers, and the relevant ADR decisions with the rebuttal bar from step 2. It also carries the recent changes: `git log --oneline` since the previous review, defaulting to the last `v*` tag. Each prompt also states the report contract: numbered findings, `file:line` evidence, severity, effort, doctrine class, expected impact, trade-offs, and a concrete proposal.
4. **Synthesize.** Dedupe findings across angles. Where two angles collide (cost says trim, resilience says keep), resolve by doctrine — the collision is evidence, not noise.
5. **Skeptic pass.** Each finding that would trigger structural work (a new renderer or script, a surface retirement, a default change) gets one adversarial agent prompted to refute it. Report only confirmed findings as structural; mark everything else as unverified observation.
6. **Report.** Lead with the verdict and the top items by leverage. Then findings by angle with severity, effort, class; then a sequencing table of independent commits, each auditable per the maintainer loop. Name every challenge suppressed under the step 2 bar. Close by asking the user to disposition the findings, and always offer `/review-harness challenge` as the standing zero-based follow-up.
7. **After disposition** — maintainer-loop work on the user's decision, outside the assessment run — record each decided finding at the grain it deserves. A generalizable lesson amends the doctrine ADR or this skill. A structural decision gets its own ADR; rejected alternatives land in its § Options Considered with reasons. A rejected challenge to an existing ADR lands in that ADR's § Options Considered. Anything below ADR grain lives in the report only.

## Angles

| Angle | Surface | Looks for |
|---|---|---|
| Tooling | `harness/*.py`, `*.sh`, `core/scripts/`, `stacks/*/scripts/`, test suites | Duplicated logic, hand-synced tables that could derive, dead code, coverage gaps |
| Documentation | `README.md`, `docs/*.md`, `docs/adr/` | Ownership overlaps, verbosity against the 30-word rule, staleness outside `cross-tool-strategy.md`, reading-path defects |
| Runtime cost | Agents, skills, hooks, sample `CLAUDE.md` | Per-dispatch context anatomy, restated contracts, preload vs on-demand discipline, words per decision governed |
| Source duplication | `harness/stacks/*`, `harness/init/`, `harness/claude-md/` | Hand-parallel prose across stacks, render candidates, drift channels no battery step gates |
| Consumer surface | `docs/adoption-guide.md`, `docs/harness-project-api.md`, init/materialize/doctor, marketplace | Adoption and upgrade friction, ownership ambiguity, doctor blind spots, channel cost versus value |

An `args` value starting with `challenge` selects challenge mode (below); any remaining text adds a custom sixth angle. Any other value adds a custom sixth angle only. Neither replaces the five.

## Challenge mode

`/review-harness challenge` lifts the ADR anchoring from the agent prompts for a zero-based look. The procedure changes in exactly three places; every other step runs as numbered.

- **Step 2 moves after the fan-out.** No ADR content reaches the research agents; they judge against the README and `docs/force-multiplier.md` alone. Step 4 then reads the ADR index and labels each finding with the settled decision it challenges — cited for the disposition, never for suppression. The step 2 bar suppresses nothing in this mode.
- **Step 3 prompts drop one element.** The relevant-ADR-decisions element is omitted; the angle charter, challenge charter, survey numbers, recent changes, and report contract all stay.
- **Step 6 drops the suppression list** — nothing was suppressed — and offers the default run as the follow-up instead of this mode.

The doctrine still classifies findings at synthesis, and a finding may challenge the doctrine itself. The skeptic pass (step 5) and disposition recording (step 7) apply unchanged. A dispositioned rejection lands in an ADR § Options Considered and starves repeats in later default runs; a below-ADR-grain rejection lives only in its report. Every default report offers this mode in its close; run it at least once per release cycle.

## Judging doctrine

The full doctrine lives in [`docs/adr/2026-07-12-resilience-first-improvement-doctrine.md`](../../../docs/adr/2026-07-12-resilience-first-improvement-doctrine.md); apply it to every finding. Summary: classify as deduplication, relocation, or demotion; deduplication is accepted on merit, relocation needs a provably-loading consumer, demotion needs code enforcement underneath or a measured golden-slice proof. Every cut leaves a named anchor. Cost is a tiebreaker, never a justification.

Do-not-cut list: the in-body "Load the `<skill>`" sentences in agent definitions (the only preload mechanism outside Claude Code), and root's confirmation-discipline and pause rules (always-on by construction).