Phase Template System - Visual Overview
Visual guide showing the complete phase documentation template system
🎨 Phase Template System - Visual Overview
Visual guide to understanding and using the phase documentation template system.
📦 System Architecture
┌─────────────────────────────────────────────────────────────────┐
│ PHASE TEMPLATE SYSTEM │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Templates │ │ Guides │ │ References │ │
│ │ (5 files) │ │ (3 docs) │ │ (Examples) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ AI Agent OR │ │
│ │ Human Developer│ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ New Phase │ │
│ │ Documentation │ │
│ └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
📁 Template Files Structure
/Templates/phases-template/
│
├── 📘 Documentation Files
│ ├── index.mdc ........................... Main index (this system)
│ ├── README.md ........................... Comprehensive guide
│ ├── AI-AGENT-WORKFLOW.md ................ Step-by-step workflow
│ ├── QUICK-REFERENCE.md .................. Quick lookup
│ └── VISUAL-SUMMARY.md ................... This file
│
└── 📄 Template Files (Copy These!)
├── index.template.mdc .................. Phase overview
├── PHASE-X-COMPLETE-PLAN.template.md ... Implementation plan
├── achievements.template.md ............ Feature tracking
├── progress.template.md ................ Daily notes
└── next-steps.template.md .............. Action items
**Actual Phase Structure** (after copying templates):
phase-X/ ├── index.mdc ├── PHASE-X-COMPLETE-PLAN.md ├── achievements.md ├── progress.md ├── next-steps.md └── context/ ⬅️ CRITICAL! ├── COMPLETE-INTEGRATION-STATUS-.md ├── FINAL-SESSION-REPORT-.md ├── HONEST-STATUS-ASSESSMENT-*.md └── [Other historical docs]
⚠️ **Always read the context/ folder FIRST before continuing work!**
---
## 🔄 Workflow Visualization
### Phase Creation Process
┌─────────────┐ │ START │ │ New Phase │ └──────┬──────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 0️⃣ READ CONTEXT FOLDER ⚠️ CRITICAL │ │ ──────────────────────── │ │ • Navigate to phase-[X-1]/context/ │ │ • Read ALL session reports │ │ • Understand achievements │ │ • Note decisions & blockers │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 1️⃣ PLANNING (20 min) │ │ ──────────────────────── │ │ • Review previous phase │ │ • Define scope & goals │ │ • Estimate timeline │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 2️⃣ STRUCTURE (10 min) │ │ ──────────────────────── │ │ • Create phase-X folder │ │ • Create context/ subfolder ⬅️ NEW! │ │ • Copy 5 template files │ │ • Rename templates │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 3️⃣ CONTENT (60-90 min) │ │ ──────────────────────── │ │ • Customize index.mdc │ │ • Fill complete plan │ │ • Initialize achievements │ │ • Create Day 0 progress │ │ • Define next steps │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 4️⃣ INTEGRATION (15 min) │ │ ──────────────────────── │ │ • Update parent index │ │ • Link previous phase │ │ • Link back to previous │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 5️⃣ VERIFICATION (10 min) │ │ ──────────────────────── │ │ • Check content complete │ │ • Test links │ │ • Run yarn docs:scan │ │ • Verify in navigation │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ 6️⃣ WORK BEGINS │ │ ──────────────────────── │ │ • Check context/ before each session │ │ • Update progress.md (every session) │ │ • Update achievements.md (milestones) │ │ • Update next-steps.md (daily) │ │ • Update index.mdc (status changes) │ │ • Add major docs to context/ folder │ └──────────────┬──────────────────────────┘ │ ▼ ┌───────┴───────┐ │ Phase Done? │ └───────┬───────┘ │ YES ──┤── NO (continue work) │ │ │ └─── (loop back to step 6) │ ▼ ┌───────────────┐ │ COMPLETION │ │ ──────────── │ │ • Final docs │ │ • Archive to │ │ context/ │ │ • Next phase │ └───────────────┘
---
## 📊 File Relationships
### How the 5 Phase Files Connect
┌─────────────────┐
│ index.mdc │
│ ═════════ │
│ Phase Overview │
│ Navigation Hub │
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ COMPLETE │ │ progress.md │ │ next-steps │
│ PLAN │ │ ═══════════ │ │ ═══════════ │
│ ═══════════ │ │ Daily Track │ │ Action List │
│ Technical │ │ What Done │ │ What's Next │
│ Roadmap │ │ Decisions │ │ Priorities │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
▼
┌─────────────────┐
│ achievements.md │
│ ═══════════════ │
│ Milestone Track │
│ Feature Complete│
└─────────────────┘
│
▼
┌─────────────────┐
│ context/ │ ⬅️ NEW!
│ ═══════════════ │
│ Historical Docs │
│ Session Reports │
│ Status Docs │
└─────────────────┘
RELATIONSHIP: ├─ index.mdc ............. Links to all others ├─ COMPLETE-PLAN ......... Reference (rarely changes) ├─ progress.md ........... Updates daily ├─ achievements.md ....... Updates per milestone ├─ next-steps.md ......... Updates daily └─ context/ .............. Read first, add at end
---
## 📝 Template Content Map
### What Goes in Each File
┌────────────────────────────────────────────────────────────────┐ │ index.mdc (OVERVIEW) │ ├────────────────────────────────────────────────────────────────┤ │ ✓ Frontmatter with metadata │ │ ✓ Timeline & high-level goals │ │ ✓ Links to all other files │ │ ✓ Current state (working vs needs work) │ │ ✓ Focus areas with time estimates │ │ ✓ Success criteria checklist │ │ ✓ Inspiring vision statement │ │ │ │ UPDATE: When status changes │ └────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐ │ PHASE-X-COMPLETE-PLAN.md (TECHNICAL PLAN) │ ├────────────────────────────────────────────────────────────────┤ │ ✓ Gap analysis (complete vs remaining) │ │ ✓ Day-by-day implementation schedule │ │ ✓ Code examples & file locations │ │ ✓ Acceptance criteria per category │ │ ✓ Critical fixes with solutions │ │ ✓ Implementation timeline table │ │ ✓ End-user experience vision │ │ │ │ UPDATE: Rarely (reference document) │ └────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐ │ achievements.md (MILESTONE TRACKING) │ ├────────────────────────────────────────────────────────────────┤ │ ✓ Major milestones (3-5) │ │ ✓ Feature checklists per milestone │ │ ✓ Carried-forward from previous phase │ │ ✓ Progress bars by category │ │ ✓ Achievement log (chronological) │ │ │ │ UPDATE: After completing milestones │ └────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐ │ progress.md (DAILY JOURNAL) │ ├────────────────────────────────────────────────────────────────┤ │ ✓ Overall progress bars │ │ ✓ Daily entries (Date, Activities, Decisions) │ │ ✓ Blockers & resolutions │ │ ✓ Technical notes & code snippets │ │ ✓ Time tracking per session │ │ ✓ Current focus & next steps │ │ │ │ UPDATE: Every work session │ └────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐ │ next-steps.md (ACTION PLAN) │ ├────────────────────────────────────────────────────────────────┤ │ ✓ Immediate actions (top 3-5) │ │ ✓ Priority levels (🔴🟡🟢⚪) │ │ ✓ Problem/Solution/Test for each │ │ ✓ Week plan (day-by-day) │ │ ✓ Success criteria │ │ ✓ Time estimates │ │ │ │ UPDATE: Daily / After completing actions │ └────────────────────────────────────────────────────────────────┘
---
## 🎯 Update Frequency Matrix
┌────────────────┬──────────────┬─────────────┬──────────────┐ │ File │ Frequency │ When │ Who │ ├────────────────┼──────────────┼─────────────┼──────────────┤ │ index.mdc │ Occasional │ Status ∆ │ AI/Human │ │ COMPLETE-PLAN │ Rarely │ Major ∆ │ AI/Human │ │ achievements │ Per Milestone│ Feature ✓ │ AI/Human │ │ progress │ Daily │ Every 🔨 │ AI/Human │ │ next-steps │ Daily │ Every 📋 │ AI/Human │ └────────────────┴──────────────┴─────────────┴──────────────┘
Legend: ∆ = Change ✓ = Complete 🔨 = Work session 📋 = Action complete
---
## 🔖 Naming Convention Visual
### File Naming Patterns
TEMPLATE FILES (in phases-template/): ┌─────────────────────────────────────┐ │ ✅ index.template.mdc │ │ ✅ PHASE-X-COMPLETE-PLAN.template.md│ │ ✅ achievements.template.md │ │ ✅ progress.template.md │ │ ✅ next-steps.template.md │ └─────────────────────────────────────┘
ACTUAL PHASE FILES (in phase-X/): ┌─────────────────────────────────────┐ │ ✅ index.mdc │ │ ✅ PHASE-9-COMPLETE-PLAN.md │ │ ✅ achievements.md │ │ ✅ progress.md │ │ ✅ next-steps.md │ └─────────────────────────────────────┘
PROGRESS NOTES (special case): ┌─────────────────────────────────────┐ │ 📝 PROGRESS_NOTE_NOV_10.md │ ← Active (ALL CAPS) │ ✅ final-session-notes.md │ ← Complete (kebab-case) └─────────────────────────────────────┘
---
## 🎨 Status & Priority Visual Guide
### Status Indicators
🎯 PLANNED ━━━━━━━━━━ Not started yet 🚀 IN PROGRESS ████████━━ Currently working ✅ COMPLETE ██████████ Finished & verified ⏳ PENDING ━━██━━━━━━ Waiting on dependencies 🔴 BLOCKED ▓▓▓▓▓▓▓▓▓▓ Cannot proceed 📝 TRACKING ━━━━━━━━━━ Ongoing documentation
### Priority Levels
🔴 CRITICAL ═══════════════ Blocks progress Fix immediately Drop everything
🟡 HIGH ─────────────── Important task Do soon High impact
🟢 MEDIUM ············· Nice to have Can wait Medium impact
⚪ LOW ··············· Optional Future work Low priority
### Progress Bars
[██████████] 100% Complete [████████░░] 80% Almost there [██████░░░░] 60% More than halfway [████░░░░░░] 40% Making progress [██░░░░░░░░] 20% Just started [░░░░░░░░░░] 0% Not started
Format: [TaskName] [████░░] 60% (6/10 hours)
---
## 🔗 Link Format Visual
### ✅ Correct Linking
Internal Documentation: Link Text └────────────────────────────────────────────────┘ No .md extension, absolute path
Same Directory: Link Text └──────────────┘ Relative, no extension
Parent Directory: Link Text └───────────────┘ Relative up one level
### ❌ Incorrect Linking
Link Text ← Has .md extension Link Text ← Includes /english/ Link Text ← Includes /docs/ Link Text ← Has .mdc extension
---
## 📅 Timeline Visualization
### Typical Phase Duration
Day 0 (Planning) │ ├─ Create documentation structure (2h) ├─ Plan implementation approach (1h) └─ Define success criteria (1h)
↓
Week 1-2 (Implementation) │ ├─ Day 1-2: Focus Area 1 ├─ Day 3-4: Focus Area 2 ├─ Day 5-6: Focus Area 3 └─ Day 7: Integration & Testing
↓
Week 3-4 (Polish & Complete) │ ├─ Testing & fixes ├─ Documentation completion ├─ Final verification └─ Prepare next phase
↓
Phase Complete! ✅
---
## 🔄 Phase Lifecycle
┌─────────────────────────────────────────────────────────┐ │ PHASE LIFECYCLE │ └─────────────────────────────────────────────────────────┘
🎯 PLANNED │ │ (Create documentation) ▼ 🚀 IN PROGRESS │ ├─── Daily Work Sessions ────┐ │ │ │ • Code implementation │ │ • Update progress.md │ │ • Check off tasks │ │ • Add new discoveries │ │ │ └────────────────────────────┘ │ │ (Milestones reached) ▼ 📊 80% Complete │ │ (Final push) ▼ ✅ COMPLETE │ │ (Planning next phase) ▼ 🎯 PLANNED (Phase X+1)
---
## 📊 Metrics & Measurement
### Phase Completion Tracking
┌────────────────────────────────────────────────┐ │ PHASE X COMPLETION DASHBOARD │ ├────────────────────────────────────────────────┤ │ │ │ Overall: [████████░░] 80% │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ Category 1 [██████████] 100% ✅ │ │ │ │ Category 2 [████████░░] 80% 🚀 │ │ │ │ Category 3 [██████░░░░] 60% 🚀 │ │ │ │ Category 4 [░░░░░░░░░░] 0% 🎯 │ │ │ └──────────────────────────────────────────┘ │ │ │ │ Time Spent: 42 / 50 hours │ │ Milestones: 3 / 4 complete │ │ Success Criteria: 5 / 7 met │ │ │ └────────────────────────────────────────────────┘
---
## 🎓 Learning Path
### For AI Agents
Step 1: Read Quick Reference (3 min) │ ▼ Step 2: Review Example Phase (10 min) │ ▼ Step 3: Follow AI Agent Workflow (15 min) │ ▼ Step 4: Create First Phase (90 min) │ ▼ Step 5: Master! 🎓
### For Humans
Step 1: Browse Visual Summary (this file) (5 min) │ ▼ Step 2: Read README.md (15 min) │ ▼ Step 3: Study Example Phases (20 min) │ ▼ Step 4: Create Your Phase (60 min) │ ▼ Step 5: Expert! 🏆
---
## 🎯 Quick Decision Tree
### Should I Create a New Phase?
Start
│
▼
┌─────────────────────────┐
│ Is previous phase │
│ ≥80% complete? │
└──────┬──────────┬───────┘
│ │
YES│ │NO
│ └──► Continue current phase
▼
┌─────────────────────────┐
│ Is there a major │
│ scope shift? │
└──────┬──────────┬───────┘
│ │
YES│ │NO
│ │
│ ▼
│ ┌─────────────────────────┐
│ │ Is current phase │
│ │ >50 hours? │
│ └──────┬──────────┬───────┘
│ │ │
│ YES│ │NO
│ │ └──► Add to current phase
│ │
└──────────┴──► CREATE NEW PHASE! ✅
---
## 📊 Resource Map
/Templates/phases-template/ │ ├─ START HERE │ ├─ index.mdc ...................... System overview │ └─ VISUAL-SUMMARY.md .............. This file │ ├─ FOR LEARNING │ ├─ README.md ...................... Complete guide │ ├─ QUICK-REFERENCE.md ............. Quick lookup │ └─ AI-AGENT-WORKFLOW.md ........... Step-by-step │ ├─ FOR CREATING │ ├─ index.template.mdc │ ├─ PHASE-X-COMPLETE-PLAN.template.md │ ├─ achievements.template.md │ ├─ progress.template.md │ └─ next-steps.template.md │ └─ FOR EXAMPLES ├─ /GoGrab-Space/user-journey/phases/phase-8/ ........ Completed phase ├─ /GoGrab-Space/user-journey/phases/phase-9/ ........ Active phase └─ /GoGrab-Space/universe-restructure/phases/phase-1/ . Has context/ folder!
---
## 🎉 Success Indicators
### Your Phase Documentation is Ready When:
✅ All 5 files created and customized ✅ Context folder created ✅ Frontmatter complete in every file ✅ All placeholders replaced ✅ Links tested and working ✅ yarn docs:scan completed ✅ Phase appears in navigation ✅ Parent index updated ✅ Previous phase linked ✅ Previous phase context/ read ✅ Day 0 progress entry written ✅ Ready to start work!
---
## 🚀 Next Steps
### After Reading This Guide
1. **Understand Structure**: You now know the 5-file system + context folder
2. **Review Templates**: Check out the `.template.md` files
3. **See Examples**: Look at Phase 8, Phase 9, and Universe Restructure Phase 1
4. **Create Phase**: Follow the workflow
5. **Start Building**: Begin your amazing work!
---
**Created**: November 10, 2025
**Last Updated**: November 10, 2025
**Template Location**: `/docs/english/Templates/phases-template/`
**Version**: 1.1 (Added context folder support)
**Status**: ✅ **VISUAL GUIDE COMPLETE**
---
**Ready to create your phase?** → [Start with AI Agent Workflow](./AI-AGENT-WORKFLOW)