ca6a34c6d4
- Add Philosophy blockquote: recommendations only, not changelog - Replace "Open Questions" with "Recommended Improvements" (delete completed, don't strikethrough) - Replace "Change Log" with "Deployment Notes" - Add RECOMMENDATIONS.md Cleanup Rules to status-update-checklist - Add docs/phases-plan.md to phase transition checklist - Add strikethrough grep check to verification commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
145 lines
4.7 KiB
Markdown
145 lines
4.7 KiB
Markdown
# 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
|