Spec 282: repeatable whole-repo review skill (/repo-review) — spec through implementation

[IanMayo]

Summary

Delivers the /repo-review skill end-to-end: a repeatable, multi-agent whole-repo audit whose findings must survive adversarial verification before they're reported, plus a /repo-review.fix fast-path from any finding to a fix PR. This PR carries the full speckit trail (spec → plan → research → data-model → contracts → tasks) and the implementation.

The distinguishing rule is verified-only: every candidate finding is checked by a separate adversarial verifier that tries to refute it; refuted and undecidable candidates are counted, not listed. The bet is a report the maintainer can act on without re-checking each claim.

What's implemented

Skill assets (.claude/)

• commands/repo-review.md — clean-tree gate, run identity, verified-only discipline, write boundary, memory + calibration, graceful degradation
• commands/repo-review.fix.md — ledger-driven fix→test→PR fast-path (mirrors /bugfix)
• review/workflow.js — Workflow orchestration: recon → per-cell review→verify pipeline (no barrier) → evidence → synthesis
• review/playbooks/{constitution,correctness,tech-debt,test-quality}.md — 20 falsifiable heuristics (CC/CB/TD/TQ), the tech-debt one framed as a Load existing result files into Attachments dropdown on plot open #172 regression check
• review/{tier-map.yaml, severity-rubric.md, report-template.md, ledger.schema.json}
• review/{ruff-strict.toml, eslint-strict.config.mjs} — report-only strict-lint configs for the evidence phase

Typed helper + tests

• scripts/review-ledger.py — strict-typed validate / reconcile / record-fix-pr, load/save with schema gate on every read and write, defect-identity reconciliation, deterministic playbook-tuning logic
• tests/repo_review/ — 36 tests (ledger validation, reconciliation lifecycle, fix-handoff preconditions, playbook/tier-map structural checks, tuning logic). All green; 75% helper coverage (uncovered = argparse wrappers, exercised via real CLI transcripts)

Docs & evidence

• docs/project_notes/decisions.md — ADR-041 (YAML+JSON-Schema over LinkML, defect-identity reconciliation, verified-only bar)
• specs/282-repo-review-skill/evidence/ — real test summary, CLI transcripts, valid+corrupt validation output, usage walkthrough, ledger sample, labelled report-format excerpt
• specs/282-repo-review-skill/media/shipped-post.md — feature blog post

Value-capture design (from the interview)

Report-only, but the loop is closed: /repo-review.fix RR-NNN turns a finding into a fix PR; each theme proposes one permanent guard (lint rule / CI gate / CLAUDE.md instruction / constitution amendment); confirmed Critical/High bugs flow into bugs.md; per-heuristic confirmed/refuted stats drive playbook tuning between runs. The headline success metric is resolution rate by the next run, not finding count.

Verification

• uv run ruff check . + ruff format --check . — clean
• uv run pytest — 2206 passed, 2 skipped, 1 xfailed (full Python suite; nothing broke)
• tests/repo_review/ — 36 passed

Not in this PR (deliberate)

• Inaugural full multi-agent run (T045 / SC-001) — the skill's behavioural acceptance test, run by the maintainer against the live repo; expensive by design (multi-million tokens) and instrumented, not executed in a build session.
• Blog publish to debrief.github.io (T054) — separate repo; run /publish-future-post there when ready.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KZAovzDhcm7S5FBB3oT8H4

[github-actions]

📋 Spec Navigator

Review this PR's specs interactively:
👉 Open in Spec Navigator
Raw spec directories changed in this PR:

• specs/282-repo-review-skill/
  _{Updated for 709b303 — the navigator reads spec content live from GitHub, so no rebuild is needed.}