# 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

## 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.