Skip to content

feat(verify): one-page plain review guide at the end of each phase (#113) - #123

Merged
rshankras merged 1 commit into
mainfrom
feat/113-review-guide
Nov 6, 2026
Merged

rshankras merged 1 commit into
mainfrom
feat/113-review-guide

Conversation

@rshankras

Copy link
Copy Markdown
Owner

Closes #113.

In plain words

At the end of a phase, deciding "is this good to keep?" meant digging through four files and the git log. Now verify writes one plain page, .planning/REVIEW-GUIDE.md, that ends with a checklist of what only you can decide.

What changed

  • New template templates/REVIEW-GUIDE.md, in this order:
    1. What changed (two sentences; screens/features; files and commits)
    2. Choices the agents made: chose / instead of / why
    3. Proof: promised features checked (feat(plan,verify): acceptance criteria as testable Given/When/Then, derived from the spec #69), tests that can fail and planted bugs (feat(build,verify): prove tests can fail — red first, then a planted bug #111), lint, coverage, design since the pin
    4. Problems found by severity, plus how many were thrown out on a second check
    5. What only you can decide, as checkboxes (open questions, assumptions to confirm, checks that need a person)
    6. Links
      At most one screen before the links. Always plain English (feat: plain-English output for everything a person reads #115), since it exists for a person deciding.
  • verify Step 6b fills it only from what already exists; the completion message says "Read first".
  • build asks agents to report choices the task didn't specify and records each as <decision chose instead-of why> in PLAN.md (lasting ones also go to STATE.md Key Decisions). Without this, section 2 would have no source.
  • autonomous names the guide in each phase recap and when it stops.
  • help Planning Files row, PLAN.md template, CLAUDE.md, CHANGELOG.

Test

./scripts/validate.sh passes. Prompt-only change; first real output comes from the next /apple:verify.

🤖 Generated with Claude Code

)

verify Step 6b writes .planning/REVIEW-GUIDE.md: what changed, agent
choices, proof, problems found, and what only you can decide, with links.
build records agent choices as <decision> lines; autonomous points to the
guide when it stops.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rshankras
rshankras merged commit 507a4a5 into main Nov 6, 2026
2 checks passed
@rshankras
rshankras deleted the feat/113-review-guide branch November 6, 2026 13:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(verify): one-page review guide at the end of each phase

1 participant