# Status Update Checklist

Instructions for keeping project documentation synchronized when status changes.
AI agents and developers should follow this checklist to prevent drift between files.

---

## When to Use This Checklist

| Trigger                                        | Scope                                       |
| ---------------------------------------------- | ------------------------------------------- |
| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files                  |
| **Milestone completed** within a phase         | Sections 1–3 only                           |
| **Architecture decision locked**               | RECOMMENDATIONS.md + new ADR in `docs/adr/` |

---

## Phase Transition Checklist

Run every item when the project moves to a new phase.

### 1. RULES.md

- [ ] Update section 6.2: change `Current phase: Phase N` to the new phase

### 2. README.md

- [ ] Update "Current Status" block (phase badge and status line)
- [ ] Update footer status line at the bottom of the file

### 3. DOCS.md

- [ ] Update footer: `**Last Updated:** Phase N (Description)`

### 4. RECOMMENDATIONS.md

- [ ] Update `Current phase` field in section 1
- [ ] Update status line in header blockquote
- [ ] Update section 5 (Recommended Improvements) — remove completed items, add new recommendations
- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below)

### 5. docs/phases-plan.md

- [ ] Update `**Phase:**` and `**Status:**` in the header
- [ ] Mark completed phase tasks as done
- [ ] Update "Current Status" section with resolved/remaining issues
- [ ] Update "Next Steps" section to reflect what's actually next

### 6. Architecture docs (if phase affects them)

- [ ] `docs/frontend/architecture.md` — lock decisions after Phase 1
- [ ] `docs/backend/architecture.md` — lock decisions after Phase 1
- [ ] Archive `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` after Phase 1

---

## Milestone Update Checklist

Run when a significant milestone is completed within the current phase.

### 1. RECOMMENDATIONS.md

- [ ] Remove completed items from section 5 (don't strikethrough — delete them)
- [ ] Add new recommendations if audit/review produced them
- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below)

### 2. README.md

- [ ] Update "Current Status" block if progress indicators changed

### 3. docs/phases-plan.md

- [ ] Mark completed tasks
- [ ] Update "Current Status" section

---

## RECOMMENDATIONS.md Cleanup Rules

**Core principle:** RECOMMENDATIONS.md = "What to do next" + "Locked decisions", NOT "What we did".

### What BELONGS in RECOMMENDATIONS.md

- Project context and locked stack decisions (sections 1–4)
- Actionable recommendations for improvements (section 5)
- Active deployment concerns (section 6)
- ADR links (section 7)
- 1-line status summary in header blockquote (e.g., "Phase 3 complete. 16 P3 items remain.")

### What does NOT belong in RECOMMENDATIONS.md

- Detailed lists of completed/resolved tasks
- Strikethrough items (~~resolved item~~) — delete them, don't cross out
- Changelog / history of changes — use git history instead
- Sections titled "COMPLETE" with detailed breakdowns
- Duplicate information about accomplished work

### Where to put completed work instead

- **Git commit messages** — detailed implementation notes
- **docs/phases/** — phase overview files
- **docs/improvements/** — improvement summaries
- **README.md** — brief high-level status in "Current Status" section

### When to clean up

- Every time a phase/milestone completes (mandatory)
- If file shows strikethrough or "RESOLVED" items
- If file exceeds 200 lines (target: ~150 lines)
- If file reads like a changelog rather than a recommendations list

### Red flags (cleanup needed)

- Sections with ~~strikethrough~~ resolved items
- Sections titled "COMPLETE: [Detailed list]"
- Multiple paragraphs describing finished work
- Same completed work mentioned in 2+ places

---

## Verification

After updating, run these commands to check consistency:

```bash
# All files should show the SAME phase number
grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases-plan.md

# Check for stale status markers
grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md

# Check for strikethrough items that should have been removed
grep -rn "~~.*~~" RECOMMENDATIONS.md
```

---

## Principles

- **Atomic** — all status changes in one commit
- **Concrete** — update actual sections listed above, not vague references
- **Verifiable** — run the grep commands to confirm consistency
- **Single source of truth** — `RULES.md` section 6.2 is the canonical phase indicator
- **Forward-looking** — RECOMMENDATIONS.md focuses on what to do next, not what was done