keel-phase-review

/keel-phase-review — end-of-phase checkpoint

Run at the end of a phase (rules.md §2). Report the checklist with pass/fail; fix gaps before proposing a commit.

Checklist:

• Working product — the phase's feature runs; include a one-line "how to test this" for the user. What only a human can verify (browser/UX, prod host, real creds) is handed off as a recipe and tracked in HANDOVER (d) — never silently assumed passed.
• Tests — relevant unit/integration (e2e if needed) written and run via make test (auto-log → reports/tests/<date>/); the phase's committed summary written to reports/tests/<date>-phase<N>.md (suites, counts, what was verified, and measured durations: suite runtime + the gate's key step timings — WHAT to time is project-specific (E2E latency, first token, query ms, batch throughput, …) — side-by-side with the previous phase's numbers so slowdowns surface at the gate, not in production); new test/fixture files one-lined in their folder README; repeatedly-run corpora (golden / regression / pilot question sets) exist as DATA files with stable ids — tests/fixtures/ or a corpus dir indexed from tests/README.md, never only inline in test code (§10.39 feeds them: every point-fixed failing case joins one); one-line summary in HANDOVER.md (rules.md §2.8); bulk outputs passed the /keel-pilot gates where applicable. Ad-hoc reports (speed tests, golden proofs) complement reports/tests/<date>-phase<N>.md — never replace it.
• Architecture — every structural change recorded in docs/architecture.md: new/changed module rows AND the component overview resynced with them (the module table is the source of truth — a stale top diagram fails this item, same contract as PLAN.md's table → diagram; rules.md §1.6).
• PLAN.md (do not skip — this is what marks the phase done) — the finished phase's gate flipped to done (+ next phase set wip, Current focus updated, diagram regenerated from the table — see /keel-plan). The Stop hook plan-phase-nudge reminds you if you end a turn having cleared a wip phase's ## Now without flipping it.
• ADRs — any significant decision captured as an ADR in docs/adr/ (+ index row).
• Docs — CLAUDE.md / docs/user_manual.md updated, or the review states why nothing user-facing changed. A still-template user_manual.md while shipped phases have user-facing behavior = FAIL (the SessionStart hook warns on this too — silence is not a pass).
• HANDOVER.md — session block added (run /keel-handover); caps respected (else /keel-distill).
• TASKS.md — done items deleted (one-liners in HANDOVER (a)); ## Discovered triaged.
• LESSONS.md — this phase's agreed rules/tests/gotchas written (rules §9.31).
• Audit — /keel-audit run over this phase's range via the skill — it writes .claude/last-audit; an inline audit that skips the marker leaves the audit-due nudge firing forever (or consciously skipped with a reason); its approved fixes applied (rules.md §4.11).
• Code review — /code-review (or the project's review flow) run over this phase's diff; each finding triaged through the verifier subagent (adversarial "try to refute") before any fix is applied: CONFIRMED → fix now · REFUTED → record with its counter-evidence · UNCERTAIN → ask the user (default: don't fix). Reviewer output is a claim, not a verdict (rules.md §4.11); deferred items get one line each in TASKS.md ## Discovered. The phase gate is the review boundary — cheaper than reviewing every session, earlier than reviewing at release.
• Secrets — git diff --cached reviewed; no .env/secrets staged (rules.md §6.18).
• Deps — if dependencies changed: lock refreshed + pip-audit clean (rules.md §7.23).

Then propose an approved commit + push (rules.md §6.15). Never push without user approval.