hakorune/docs/private/roadmap/phases/phase-20-variant-box/INDEX.md

# Phase 20 VariantBox - Complete Documentation Index

**Last Updated**: 2025-10-08
**Status**: Ready for Implementation (after Phase 15.7)

---

## 🎯 Quick Navigation

### **START HERE**
- **[README.md](./README.md)** - Phase 20 overview and introduction
- **[ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md)** - ⭐ Quick start guide (2-page summary)

### **For Implementers**
- **[ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md)** - ⭐ Complete 12-17 day plan (main document)
- **[ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md)** - Visual timeline and Gantt charts
- **[DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md)** - Daily execution tracking template

### **For Designers/Reviewers**
- **[DESIGN.md](./DESIGN.md)** - VariantBox complete design
- **[@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md)** - @enum technical spec
- **[@match-macro-implementation-spec.md](./@match-macro-implementation-spec.md)** - @match technical spec

---

## 📚 Document Categories

### **1. Project Planning & Execution** (New: 2025-10-08)

**Primary Documents**:
1. **[ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md)** (41KB)
   - Complete project plan for Choice A'' (macro-only approach)
   - Daily task breakdown (Days 1-17)
   - Risk analysis with mitigation strategies
   - Success criteria and acceptance tests
   - Rollback plans (Option 1: @enum-only, Option 2: Full rollback)
   - Quality gates and go/no-go decisions
   - 📖 **Use this**: As your main execution guide

2. **[ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md)** (5.6KB)
   - 2-page summary of project plan
   - 3-week schedule at a glance
   - Critical risks (top 3)
   - Quick commands and daily checklist
   - 📖 **Use this**: For daily reference

3. **[ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md)** (13KB)
   - Gantt-style timeline visualization
   - Critical path analysis
   - Resource allocation by week
   - Time budget breakdown
   - Monte Carlo simulation results (14-15 day median)
   - Daily success indicators
   - 📖 **Use this**: For progress tracking and stakeholder updates

4. **[DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md)** (12KB)
   - Copy-paste templates for each day
   - Task checklists, issue tracking, test results
   - Quality gate decision templates
   - Weekly summary templates
   - 📖 **Use this**: Copy relevant section each day, fill in as you work

---

### **2. Technical Design** (Original: 2025-10-08)

**Architecture Documents**:
1. **[DESIGN.md](./DESIGN.md)** (11KB)
   - VariantBox core design
   - Philosophical alignment (Everything-is-Box, MIR16 維持)
   - @enum/@match desugaring examples
   - Comparison with alternatives (MapBox, Box inheritance, MIR extension)
   - Future extensions (SymbolBox, static exhaustiveness, GADT)
   - 📖 **Use this**: For understanding design decisions

2. **[@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md)** (41KB)
   - Complete @enum macro specification
   - Parser changes, AST nodes, macro expansion
   - Code generation details
   - Test patterns and edge cases
   - 📖 **Use this**: When implementing @enum (Days 1-5)

3. **[@match-macro-implementation-spec.md](./@match-macro-implementation-spec.md)** (37KB)
   - Complete @match macro specification
   - Pattern matching semantics
   - Desugaring to if-else chain
   - Exhaustiveness checking (runtime)
   - 📖 **Use this**: When implementing @match (Days 6-11)

---

### **3. Result Box Specific** (Original: 2025-10-08)

**Result<T,E> Design Series**:
1. **[RESULT_BOX_COMPLETE_DESIGN.md](./RESULT_BOX_COMPLETE_DESIGN.md)** (16KB)
   - Complete Result<T,E> design
   - Comparison: Manual ResultBox vs @enum Result
   - Migration roadmap
   - 📖 **Use this**: For Result-specific implementation (Day 12)

2. **[RESULT_BOX_MIGRATION_PLAN.md](./RESULT_BOX_MIGRATION_PLAN.md)** (10KB)
   - Step-by-step migration guide
   - Backward compatibility strategy
   - Risk mitigation for existing code
   - 📖 **Use this**: For Day 12 (Option/Result v2)

3. **[RESULT_BOX_SUMMARY.md](./RESULT_BOX_SUMMARY.md)** (5.2KB)
   - 1-minute summary
   - Quick reference for Result usage
   - 📖 **Use this**: For quick lookups

4. **[result_box_v2_reference.hako](./result_box_v2_reference.hako)** (467 lines)
   - Reference implementation with @enum
   - Copy-paste starting point
   - 📖 **Use this**: As implementation template (Day 12)

---

### **4. Quick References**

**Quick Start Guides**:
1. **[@enum-quick-start.md](./@enum-quick-start.md)** (6.2KB)
   - @enum syntax cheatsheet
   - Common patterns
   - Quick examples
   - 📖 **Use this**: During @enum implementation (Days 1-5)

2. **[@match-quick-start.md](./@match-quick-start.md)** (9.9KB)
   - @match syntax cheatsheet
   - Pattern matching examples
   - Common pitfalls
   - 📖 **Use this**: During @match implementation (Days 6-11)

3. **[README-match-implementation.md](./README-match-implementation.md)** (8.2KB)
   - @match implementation FAQ
   - Troubleshooting guide
   - 📖 **Use this**: When debugging @match issues

---

## 🚀 Getting Started Checklist

### **Before Day 1**
- [ ] Read: [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) (15 min)
- [ ] Read: [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 1 (Daily Tasks) (30 min)
- [ ] Read: [DESIGN.md](./DESIGN.md) (30 min)
- [ ] Review: Existing macro system (`src/macro/mod.rs`, `apps/macros/loop_normalize_macro.nyash`)
- [ ] Prepare: Copy [DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md) Day 1 section
- [ ] Run: Baseline smoke tests (`tools/smokes/v2/run.sh --profile quick`) for regression detection

### **Day 1 Morning**
- [ ] Review: [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Day 1 section (5 min)
- [ ] Review: [@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md) Parser section (15 min)
- [ ] Start: Daily log (copy from template)
- [ ] Begin: Parser implementation

### **Each Day**
- [ ] Morning: Review day's section in [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) (5 min)
- [ ] Work: Follow daily task list
- [ ] Track: Fill in daily log template as you work
- [ ] EOD: Update CURRENT_TASK.md with summary
- [ ] EOD: Review tomorrow's tasks

### **At Quality Gates (Days 5, 11, 14)**
- [ ] Run: All tests (unit + smoke)
- [ ] Measure: Performance (benchmark)
- [ ] Decide: Go / Caution / No-Go (use template in [DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md))
- [ ] Update: CURRENT_TASK.md with gate decision
- [ ] If No-Go: Consult rollback plans in [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 4

---

## 📖 Reading Order Recommendations

### **First-Time Reader (30 min)**
1. [README.md](./README.md) (5 min) - Overview
2. [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) (10 min) - Summary
3. [DESIGN.md](./DESIGN.md) (15 min) - Design rationale

### **Implementer (1-2 hours)**
1. [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) (10 min)
2. [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 1 (Day 1-17 tasks) (30 min)
3. [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 2 (Risk Analysis) (15 min)
4. [ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md) (10 min) - Visualization
5. [@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md) (20 min) - Technical details

### **Reviewer/Stakeholder (15 min)**
1. [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) (5 min)
2. [ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md) (5 min) - Timeline
3. [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 3 (Success Criteria) (5 min)

---

## 🔍 Find Information By Topic

### **Timeline & Schedule**
- Overall timeline → [ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md)
- Daily tasks → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 1
- Quick schedule → [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) Section "3-Week Schedule"

### **Risks & Mitigation**
- Complete risk analysis → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 2
- Top 3 risks → [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) Section "Critical Risks"
- Risk timeline → [ENUM_MATCH_TIMELINE.md](./ENUM_MATCH_TIMELINE.md) Section "Risk Timeline"

### **Success Criteria & Testing**
- Complete criteria → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 3
- Quality gates → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 7
- Test patterns → [@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md) + [@match-macro-implementation-spec.md](./@match-macro-implementation-spec.md)

### **Rollback Plans**
- Complete plans → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 4
- Quick reference → [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) Section "Rollback Options"

### **Design Details**
- Architecture → [DESIGN.md](./DESIGN.md)
- @enum specifics → [@enum-macro-implementation-spec.md](./@enum-macro-implementation-spec.md)
- @match specifics → [@match-macro-implementation-spec.md](./@match-macro-implementation-spec.md)
- Result specifics → [RESULT_BOX_COMPLETE_DESIGN.md](./RESULT_BOX_COMPLETE_DESIGN.md)

### **Implementation Guidance**
- Daily tasks → [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 1
- Quick commands → [ENUM_MATCH_QUICK_START.md](./ENUM_MATCH_QUICK_START.md) Section "Quick Commands"
- Daily tracking → [DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md)

---

## 📊 Document Statistics

**Total Documents**: 14
**Total Size**: ~280 KB
**Total Reading Time**: ~2-3 hours (full coverage)
**Minimum Reading Time**: 30 min (quick start)

**By Category**:
- Planning & Execution: 4 docs (~71 KB)
- Technical Design: 3 docs (~89 KB)
- Result Box Specific: 4 docs (~56 KB)
- Quick References: 3 docs (~24 KB)

---

## 🎯 Key Success Factors

### **Use the Right Document at the Right Time**
- **Planning phase** → ENUM_MATCH_PROJECT_PLAN.md
- **Daily work** → ENUM_MATCH_QUICK_START.md + DAILY_LOG_TEMPLATE.md
- **Implementation details** → @enum/@match implementation specs
- **Troubleshooting** → README-match-implementation.md
- **Progress tracking** → ENUM_MATCH_TIMELINE.md

### **Don't Skip Quality Gates**
- Gate 1 (Day 5): 10/10 tests PASS or reassess
- Gate 2 (Day 11): 15/15 tests PASS or rollback to @enum-only
- Gate 3 (Day 14): ALL smoke tests PASS or full rollback

### **Track Progress Daily**
- Use [DAILY_LOG_TEMPLATE.md](./DAILY_LOG_TEMPLATE.md) every day
- Update CURRENT_TASK.md at EOD
- Escalate blockers early (don't wait for gates)

---

## 🔗 External References

### **Related Phases**
- Phase 15.7: Selfhost completion (prerequisite)
- Phase 16: Macro Revolution (@derive implementation)
- Phase 20.0-20.5: Macro Full Features (foundation)
- Phase 25: Type System (static exhaustiveness checks)

### **Implementation References**
- Existing macros: `apps/macros/loop_normalize_macro.nyash` (393 lines)
- Pattern matching: `src/macro/pattern.rs` (252 lines)
- Macro engine: `src/macro/engine.rs`
- Option/Result: `apps/lib/boxes/option.hako`, `apps/lib/boxes/result.hako`

### **Design Background**
- ChatGPT Pro proposal (2025-10-08)
- Ultrathink 4-task analysis (consistency, alternatives, risks, impact)
- Phase 20 design discussions

---

## 🚨 Important Notes

### **Prerequisites**
- ✅ Phase 15.7 complete (selfhost achieved)
- ✅ StringBox/ArrayBox/MapBox stable
- ✅ Macro system basic functionality (Phase 16 interim OK)

### **Assumptions**
- MIR16 instruction set remains frozen
- Everything-is-Box principle maintained
- Macro-only approach (no runtime/MIR changes)

### **Limitations (Documented)**
- Runtime exhaustiveness checking only (static checking in Phase 25)
- StringBox tags (SymbolBox optimization in Phase 25)
- Pattern matching limited to single-level (no nested patterns in MVP)

---

## 📝 Change Log

**2025-10-08**:
- ✅ Created complete project plan (ENUM_MATCH_PROJECT_PLAN.md)
- ✅ Created quick start guide (ENUM_MATCH_QUICK_START.md)
- ✅ Created visual timeline (ENUM_MATCH_TIMELINE.md)
- ✅ Created daily log template (DAILY_LOG_TEMPLATE.md)
- ✅ Updated README.md with plan references
- ✅ Created this index document

**Previous** (Before 2025-10-08):
- DESIGN.md: Complete VariantBox design
- Result Box design series (4 documents)
- @enum/@match implementation specs
- Quick references and guides

---

**Status**: ✅ READY FOR IMPLEMENTATION
**Approval**: Pending Phase 15.7 completion
**Next Action**: Wait for Phase 15.7, then begin Day 1 preparation

**Questions?** See [README.md](./README.md) or consult [ENUM_MATCH_PROJECT_PLAN.md](./ENUM_MATCH_PROJECT_PLAN.md) Section 8 (Communication Plan)