boma/.claude/commands/review-repo.md

# Review the repo for staleness, drift, and contradictions

Audit the whole repo across four dimensions, apply only the safe/obvious fixes,
report the rest, and write a tracked report to `docs/reviews/`.

## Dimensions (equal weight)

1. **Cruft / staleness** — code, comments, or notes left behind after the thing they
   addressed was resolved; commented-out blocks; done-but-undeleted TODOs; orphans.
2. **Design conformance** — does the repo obey the ADRs and CLAUDE.md conventions
   (FQCN, tags, `rolename__var`, nested vault, Makefile-as-interface, etc.)?
3. **Consistency & intent** — contradictions (doc↔doc and doc↔code), overlaps,
   duplication, and whether intent is actually documented.
4. **Docs-vs-reality drift** — do `STATUS.md` and the ADRs match what is actually
   built?

## Rubric (the source of truth to measure against)

- `docs/decisions/` (ADRs) — the design decisions.
- `CLAUDE.md` — the conventions.
- `STATUS.md` — what is actually built vs only planned.

## Process

### Phase 0 — deterministic pre-scan
Run `python3 scripts/repo-scan.py > /tmp/repo-scan.json`. It returns the **inventory**
(roles, ADRs, runbooks, playbooks, scripts — your shard list) and **exact findings**
(markers, broken refs, unencrypted vaults). Fold these into the report verbatim.

It also emits two deferral checks (see Phase 2): `open-deferred-item` (every still-open
ADR "Deferred/Open" entry — a checklist to confirm) and `stale-deferred` (an entry
another file describes as resolved but which isn't marked resolved in place —
high-confidence, usually auto-fixable by marking the source ADR's entry RESOLVED).

### Phase 1 — fan-out judgement review
Scale to repo size:
- **Small** (≤ ~10 roles, like boma today): a few sub-agents, or one pass per area.
- **Large** (many roles/docs — heading toward AnsibleBaobabV4's 100+ roles): fan out
  **one reviewer per shard** (role / doc-cluster / ADR group) in parallel via the
  Agent tool, or the Workflow orchestrator for the biggest sweeps.

Give each reviewer: its slice **plus the rubric** and the four dimensions. Each
returns structured findings — `{dimension, severity (high|medium|low),
location (file:line), description, suggested_fix, auto_fixable (bool)}`.

### Phase 2 — synthesis
- Merge and dedupe all findings (deterministic + reviewer).
- Run **one cross-cutting reviewer** over the full ADR set + `STATUS.md` + `CLAUDE.md`
  to catch contradictions that span files (per-shard agents can't see these).
- **Resolve the deferral checklist.** For every `open-deferred-item` from Phase 0,
  judge whether it is *genuinely* still open: search later ADRs / `STATUS.md` for a
  decision on that subject (a deferred item often resolves silently when a later ADR
  lands). If it has been decided, it is a stale-deferred finding — the fix is to mark
  that entry RESOLVED in its **source ADR's** Deferred list (the spot the resolving
  ADR's own change won't have touched). Treat every `stale-deferred` finding as
  high-confidence. This is the recurring miss logged in `docs/FRICTION.md`.
- Diff against the previous run's `docs/reviews/<prev>-findings.json` and tag each
  finding **new / recurring / resolved**.
- Prioritise by severity; split into auto-fixable vs report-only.

### Phase 3 — act
- Apply **only** the safe/obvious fixes (allow-list below). Run `make lint` after;
  revert any fix that breaks it.
- Write the report and machine findings (see Output) and generate a follow-up prompt.
- Commit per CLAUDE.md git conventions (small/safe → `main`; a larger batch → a
  branch, diff shown first). Summarise to the user: counts, what was auto-fixed, the
  top open findings, and the follow-up prompt.

## Auto-fix allow-list — safe and obvious ONLY

**Allowed:** typos in prose/comments; broken cross-reference paths (repoint to the
correct existing path); dead commented-out blocks with no explanatory value;
obviously-stale comments that contradict the code they annotate; trivial formatting;
updating a doc reference to a renamed file.

**Never:** anything that changes runtime behaviour, logic, variables, or task order;
anything touching secrets, vault files, or credentials; anything where intent is
ambiguous or the answer is a judgement call; deleting files; resolving a
contradiction between two ADRs (that is a design decision — report it).

**When unsure, REPORT — do not fix.**

## Output (written to `docs/reviews/`)

- `docs/reviews/<YYYY-MM-DD>-review.md` — human report.
- `docs/reviews/<YYYY-MM-DD>-findings.json` — machine-readable (next run's diff + the
  cron email payload).
- `docs/reviews/latest.md` — overwrite with a copy of the newest report.

Report contents: run metadata (date, reviewed commit SHA); summary counts by
dimension/severity; auto-fixes applied (with file list); open findings (prioritised,
grouped by dimension, each with location + suggested fix + new/recurring tag); and a
generated, copy-pasteable **follow-up prompt**. See `docs/reviews/README.md`.

## Headless / cron (future — `docs/TODO.md` "Scheduled work")

When run non-interactively (`claude -p`, e.g. a fortnightly cron): **report only** —
do not apply fixes or push to `main`. Write the report artifact and email its summary
+ the follow-up prompt to the maintainer via the machine's email skill (other
projects on this host already use it). The report file is the email payload. Validate
the headless email path when wiring the cron job.