Checklists¶

Phase-by-phase verification checklists for Document-Driven Development

Overview¶

Use these checklists to verify completion of each phase. Check off items as you complete them to ensure nothing is missed.

Phase 0: Planning & Alignment¶

[ ] Problem clearly framed with scope and success criteria
[ ] Reconnaissance complete (file crawling if large)
[ ] Multiple proposals considered (2-3 options)
[ ] Trade-offs discussed openly
[ ] Shared understanding achieved and verified
[ ] AI can articulate plan back accurately
[ ] Master plan captured (TodoWrite or ai_working/ file)
[ ] Philosophy alignment verified
[ ] User explicitly approves proceeding

Ready for: Phase 1

Phase 1: Documentation Retcon¶

[ ] File index generated programmatically
[ ] File crawling approach used systematically
[ ] Each file processed individually (not batch marked)
[ ] Full file content read before changes
[ ] Retcon writing rules followed strictly
[ ] Maximum DRY enforced (duplicates deleted)
[ ] Global replacements used as helper only (not substitute)
[ ] Conflicts detected and resolved (if any)
[ ] Progressive organization applied
[ ] Verification pass complete
[ ] NOT committed yet - ready for approval
[ ] All files in checklist marked [x]

Ready for: Phase 2

Phase 2: Approval Gate¶

[ ] Human reviewed all documentation
[ ] Design verified correct and complete
[ ] Terminology verified accurate and canonical
[ ] Complexity captured honestly
[ ] Examples verified realistic and correct
[ ] Philosophy compliance confirmed
[ ] No duplication or context poisoning sources
[ ] Progressive organization makes sense
[ ] Human-readable and clear
[ ] Iterate with human until approved
[ ] User explicitly approves: "proceed to implementation"
[ ] NOW commit documentation with approval note
[ ] NOT pushed yet - implementation next

Ready for: Phase 3

Phase 3: Implementation Planning¶

[ ] Code reconnaissance complete (file crawling)
[ ] Conflicts between docs and code resolved
[ ] Implementation plan documented in detail
[ ] Work properly right-sized (fits in context window)
[ ] Dependencies identified
[ ] Proper sequencing determined
[ ] Complexity check performed
[ ] Effort estimated
[ ] Philosophy alignment verified

Ready for: Phase 4

Phase 4: Code Implementation¶

[ ] File crawling approach used for large changes
[ ] Full context loaded before each subtask
[ ] Related docs, code, and tests read first
[ ] Conflicts detected and paused on (if any)
[ ] Code matches docs exactly
[ ] No deviation without doc update first
[ ] Changes committed incrementally by logical feature
[ ] Clear commit messages
[ ] All implementation checklist items marked complete

Ready for: Phase 5

Phase 5: Testing & Verification¶

[ ] All documented examples tested
[ ] Examples work when copy-pasted
[ ] User testing complete (AI tested as actual user)
[ ] User testing report created (detailed in ai_working/)
[ ] Recommended smoke tests provided (for human)
[ ] Output matches documentation descriptions
[ ] Error handling tested (invalid inputs, edge cases)
[ ] Cross-cutting scenarios tested
[ ] All code-based tests passing: make test
[ ] All checks passing: make check
[ ] Performance acceptable
[ ] Critical issues resolved or documented
[ ] Docs updated if mismatches found (with approval)

Ready for: Phase 6

Phase 6: Cleanup & Push¶

[ ] Temporary files removed or archived
[ ] ai_working/ reviewed and cleaned
[ ] All tests passing
[ ] All checks passing
[ ] Documentation and code in perfect sync
[ ] No temporary/debug code
[ ] Commit messages clear
[ ] Philosophy principles followed throughout
[ ] Final verification complete
[ ] Changes pushed to remote

DDD Cycle Complete!

Quick Verification Commands¶

Check Documentation Consistency¶

# No old terminology
grep -rn "old-term" docs/

# No historical references
grep -rn "previously\|used to\|old way" docs/

# No future tense
grep -rn "will be\|coming soon" docs/

# No duplicate concepts
grep -rn "concept definition" docs/  # Should be single location

Check Implementation Quality¶

# Run tests
make test

# Run checks
make check

# Verify no debug code
grep -rn "print(\|console.log\|debugger" --include="*.py" --include="*.js"

# Check git status
git status  # Should be clean

Check Context Poisoning¶

# No duplicate documentation
# Each concept in ONE place

# Verify with:
grep -r "term-to-check" docs/  # Should return single canonical location

Master Checklist (All Phases)¶

Use this for complete DDD cycle verification:

Planning: Phase 0 complete Documentation: Phase 1 complete, Phase 2 approved & committed Implementation: Phase 3 planned, Phase 4 implemented & committed Verification: Phase 5 tested (user + code) Completion: Phase 6 cleaned & pushed

Success criteria:

✅ Documentation and code never diverged
✅ Zero context poisoning
✅ All tests passing
✅ Clean git history
✅ Philosophy principles followed
✅ User testing complete
✅ Ready for human review

Return to: Reference | Main Index

See Also: Tips for Success | Common Pitfalls