sjat
de38d1c68b
Match the uppercase convention of the other top-level docs; includes the new Scheduled-work and sanity-check items, and repoints references in STATUS.md and the /review-repo command. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
89 lines
4.5 KiB
Markdown
89 lines
4.5 KiB
Markdown
# 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.
|