AI_template/.claude/status-update-checklist.md

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:

# 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