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.

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).
• 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.