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>
67 lines
3.5 KiB
Markdown
67 lines
3.5 KiB
Markdown
# 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.
|