22d49b2c9a
Adds 3 new topic files (ai-parallel-agents, api-integration, python-patterns) and extends 21 existing topic files with new gotchas and patterns surfaced from memory across tracked projects. Index updated accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.5 KiB
Milestones & Reflections
Milestone Structure
Break projects into numbered milestones (M1, M2, ...). This provides clear checkpoints, measurable progress, and natural reflection points.
Milestone Completion Checklist
Every milestone MUST include:
1. Verification Script
scripts/verify-m<N>.sh — automated checks confirming all milestone outcomes.
- Idempotent, non-destructive, returns non-zero on failure
- Colour output (green/red) for pass/fail
- Environment-resilient (no sudo, test from accessible side)
- Check for default/insecure credentials
2. Milestone Reflection
Write memory/m<N>-reflection.md by reviewing the entire conversation from milestone start. Cover:
- Process improvements: What slowed us down? Wrong assumptions? Where did we go in circles? What would make this faster if redone from scratch?
- Key knowledge for reproduction: Critical facts, gotchas, non-obvious config details, version-specific quirks, debugging detours
- Scripts and automation: Existing tools that proved valuable, new scripts to build, patterns to extract into reusable automation
- Future improvements: Ideas that surfaced but don't belong in current scope — add to FUTURE.md
3. Updated README.md
Ensure the scripts section, milestone table, and setup steps are current.
4. Updated CLAUDE.md
Reflect new repo structure, conventions, and patterns discovered during the milestone.
Reflection Quality
Good reflections capture:
- Commit stats (total commits, fix percentage) to measure validation discipline
- Longest detour and root cause
- Most avoidable waste and what would have prevented it
- Concrete checklist items for future similar work
Always Push Partial Work, Even on Test Failure
When dispatching agent tasks that commit work on exit, push the branch even when tests fail. Example failure mode: a task with 88/88 of its own tests passing but an unrelated dependency failure in the full suite had its work discarded because finalize was gated on "tests passed".
Partial work is almost always more valuable than nothing — the exit code and metadata still signal failure, and downstream users can cherry-pick or inspect the branch.
Rule: finalize/commit/push actions should not be gated on success. Only higher-level decisions (branch labels, PR creation, auto-merge eligibility) should key off test outcomes.
Write Milestone Verify Scripts Manually, Not as Agent Deliverables
When agents complete tasks in a decomposed milestone, each agent naturally writes a verify script that covers only its own slice. If one of those slice-scoped scripts is labelled the milestone verify script, "milestone verified" really means "one slice verified" — the cross-slice integration is unchecked.
Rule: always write the milestone-level verify script manually, or dispatch it as a separate task whose input is the full milestone scope. Never fold milestone verification into one of the feature-implementation tasks.
Evaluate Content Placement Before Building
Before creating a new document, system, or catalog, discuss where it belongs conceptually. Different content types have different lifecycles:
- Accumulated learnings → memory files (gotchas, process lessons)
- Authoritative maintained maps → CLAUDE.md or dedicated reference docs
- Behavioral contracts → spec files
- Active work state → CONTEXT.md
Picking the wrong home creates maintenance friction later. A five-minute placement discussion saves a future migration.