Skip to content

NAVIGATION_GUIDE.md

Latest commit

 

History

History
385 lines (308 loc) · 12.7 KB

NAVIGATION_GUIDE.md

File metadata and controls

385 lines (308 loc) · 12.7 KB

StackFastPro Navigation Guide

Quick reference for finding what you need

🎯 "I want to..."

Start Implementing NOW

→ .kiro/specs/stackfast-full-stack-builder/tasks.md

  • Scroll to "Week-by-Week Implementation Guide"
  • Start with Week 1, Day 1
  • Follow morning/afternoon tasks

Track My Daily Progress

→ PROGRESS.md ⭐ UPDATE DAILY!

  • Check off completed tasks
  • Update progress bars
  • Add daily notes
  • Track milestones

Get Today's Quick Reference

→ QUICK_REFERENCE.md ⭐ PRINT THIS!

  • One-page cheat sheet
  • Today's goals
  • Key files to modify
  • Testing commands

Understand What to Build

→ .kiro/specs/stackfast-full-stack-builder/requirements.md

  • 14 requirements with acceptance criteria
  • User stories in EARS format
  • Glossary of terms

Understand How to Build It

→ .kiro/specs/stackfast-full-stack-builder/design.md

  • Architecture diagrams
  • Component interfaces
  • Data models
  • Performance strategies

See Code Examples

→ IMPLEMENTATION_GAPS.md

  • System-by-system gap analysis
  • Code snippets for each system
  • Implementation notes

Get Day-by-Day Guidance

→ QUICK_START_GUIDE.md

  • Detailed code examples
  • Testing strategies
  • Troubleshooting tips

Understand the Big Picture

→ FORWARD_PLAN.md

  • 4-week strategic overview
  • Current state analysis
  • Risk mitigation
  • Success metrics

See Visual Roadmap

→ VISUAL_ROADMAP.md

  • Week-by-week visualization
  • Progress tracking
  • Milestone checklist

Learn from Past Mistakes

→ LESSONS_LEARNED.md

  • Why StackFast-101 failed
  • 6 critical mistakes to avoid
  • Success principles

Understand Recent Decisions

→ .kiro/specs/stackfast-full-stack-builder/CHANGELOG.md

  • Recent spec updates
  • Rationale for decisions
  • Files changed

Follow Coding Standards

→ .kiro/steering/stackfast-standards.md

  • Coding patterns
  • Common pitfalls
  • Best practices

📁 File Organization

Spec Files (Official)

.kiro/specs/stackfast-full-stack-builder/
├── requirements.md    ← What to build
├── design.md          ← How to build it
├── tasks.md           ← When to build it (with week-by-week guide)
└── CHANGELOG.md       ← Why decisions were made

Planning Documents (Reference)

Root directory/
├── START_HERE.md              ← Entry point
├── FORWARD_PLAN.md            ← Strategic overview
├── IMPLEMENTATION_GAPS.md     ← Gap analysis with code
├── QUICK_START_GUIDE.md       ← Tactical guide
├── LESSONS_LEARNED.md         ← Historical context
├── VISUAL_ROADMAP.md          ← Visual guide
├── SPEC_UPDATE_SUMMARY.md     ← What changed
├── NAVIGATION_GUIDE.md        ← This file
├── PROGRESS.md                ← Daily progress tracker (UPDATE DAILY!)
└── QUICK_REFERENCE.md         ← One-page cheat sheet

Steering Rules (Standards)

.kiro/steering/
└── stackfast-standards.md     ← Coding standards

🗺️ Document Relationships

┌─────────────────────────────────────────────────────────┐
│                    ENTRY POINTS                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  New to project?        → START_HERE.md                 │
│  Ready to code?         → tasks.md (Week 1, Day 1)      │
│  Need requirements?     → requirements.md               │
│  Need architecture?     → design.md                     │
│                                                          │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                  IMPLEMENTATION                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Daily tasks            → tasks.md (Week-by-Week)       │
│  Code examples          → IMPLEMENTATION_GAPS.md        │
│  Detailed guide         → QUICK_START_GUIDE.md          │
│  Coding standards       → stackfast-standards.md        │
│                                                          │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                    REFERENCE                             │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Strategic plan         → FORWARD_PLAN.md               │
│  Visual roadmap         → VISUAL_ROADMAP.md             │
│  Historical context     → LESSONS_LEARNED.md            │
│  Recent changes         → CHANGELOG.md                  │
│                                                          │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start Paths

Path 1: "I have 1 hour"

  1. Read FORWARD_PLAN.md Executive Summary (5 min)
  2. Read tasks.md Week 1 overview (5 min)
  3. Read QUICK_START_GUIDE.md Day 1 (10 min)
  4. Start coding Week 1, Day 1 tasks (40 min)

Path 2: "I have 30 minutes"

  1. Read START_HERE.md (5 min)
  2. Read tasks.md Week 1, Day 1 (10 min)
  3. Start coding (15 min)

Path 3: "I have 15 minutes"

  1. Open tasks.md
  2. Go to Week 1, Day 1
  3. Start first morning task

📊 Progress Tracking

Current Status

Foundation:  ████████████████████ 100% ✅
Core Engine: ████░░░░░░░░░░░░░░░  20% 🔴
UI Layer:    ██░░░░░░░░░░░░░░░░░  10% 🔴
Features:    ░░░░░░░░░░░░░░░░░░░   0% ⬜
Testing:     ░░░░░░░░░░░░░░░░░░░   0% ⬜

Overall:     ██████░░░░░░░░░░░░░  30% 🟡

Track Progress In

  • tasks.md - Check off completed tasks
  • VISUAL_ROADMAP.md - Update progress bars
  • CHANGELOG.md - Document decisions

🎓 Learning Resources

Before Starting

  • Read LESSONS_LEARNED.md - Avoid past mistakes
  • Read requirements.md - Understand what to build
  • Read design.md - Understand architecture

While Implementing

  • Reference tasks.md - Daily guidance
  • Reference IMPLEMENTATION_GAPS.md - Code examples
  • Reference stackfast-standards.md - Coding patterns

When Stuck

  • Check QUICK_START_GUIDE.md - Troubleshooting
  • Check design.md - Architecture decisions
  • Check CHANGELOG.md - Recent changes

🔍 Search Tips

Find Specific Information

Requirements:

# Search in requirements.md
grep -i "compatibility" .kiro/specs/stackfast-full-stack-builder/requirements.md

Code Examples:

# Search in IMPLEMENTATION_GAPS.md
grep -i "evaluateRules" IMPLEMENTATION_GAPS.md

Tasks:

# Search in tasks.md
grep -i "rules engine" .kiro/specs/stackfast-full-stack-builder/tasks.md

📝 Document Purpose Summary

Document Purpose When to Use
START_HERE.md Entry point with decision tree First time, getting oriented
requirements.md What to build (14 requirements) Understanding scope
design.md How to build it (architecture) Understanding structure
tasks.md When to build it (4-week plan) Daily implementation
FORWARD_PLAN.md Strategic overview Understanding big picture
IMPLEMENTATION_GAPS.md Gap analysis with code Finding code examples
QUICK_START_GUIDE.md Tactical guide Day-by-day guidance
VISUAL_ROADMAP.md Visual representation Seeing progress
LESSONS_LEARNED.md Historical context Avoiding mistakes
CHANGELOG.md Recent decisions Understanding changes
stackfast-standards.md Coding standards Writing code
SPEC_UPDATE_SUMMARY.md What changed today Understanding update
NAVIGATION_GUIDE.md This file Finding things
PROGRESS.md Daily progress tracker Tracking daily work
QUICK_REFERENCE.md One-page cheat sheet Daily quick reference

🎯 Critical Path

Week 1: Rules Engine → Score Calculator → State Management → UI Wiring
   ↓
Week 2: Complete State → Wire All Components → Responsive Design
   ↓
Week 3: Suggestions → Export Recipes → File Generators → Archive
   ↓
Week 4: Tests → Accessibility → Performance → Deploy

Start here: Week 1, Day 1 in tasks.md

✅ Daily Workflow

Every Morning

  1. Open PROGRESS.md
  2. Find current day (e.g., Week 1, Day 2)
  3. Read morning tasks
  4. Update QUICK_REFERENCE.md with today's goals
  5. Start implementing

Every Afternoon

  1. Complete morning tasks
  2. Check off tasks in PROGRESS.md
  3. Read afternoon tasks
  4. Continue implementing

Every Evening

  1. Run tests: npm test
  2. Check types: npm run type-check
  3. Check off completed tasks in PROGRESS.md
  4. Add daily notes
  5. Commit code
  6. Review next day's tasks

🆘 When You Need Help

Implementation Questions

→ IMPLEMENTATION_GAPS.md (code examples)

Process Questions

→ QUICK_START_GUIDE.md (step-by-step)

Architecture Questions

→ design.md (architecture)

Requirement Questions

→ requirements.md (what to build)

Historical Questions

→ LESSONS_LEARNED.md (past mistakes)

Recent Changes

→ CHANGELOG.md (decisions)

🎉 Success Checklist

Week 1

  • Rules engine evaluates all types
  • Score calculation works
  • Worker communication works
  • Can select tools
  • Score updates in real-time

Week 2

  • Full UI is interactive
  • Diagnostics display
  • Cardinality enforced
  • Score breakdown shows
  • Responsive on all devices

Week 3

  • Suggestions appear
  • Accepting suggestion works
  • Export generates files
  • ZIP downloads
  • Complete user journey works

Week 4

  • 80%+ code coverage
  • All tests pass
  • WCAG 2.1 AA compliant
  • <50ms rule evaluation
  • Zero critical bugs
  • 🚀 DEPLOYED

📞 Quick Reference Card

┌─────────────────────────────────────────────────────────┐
│                  QUICK REFERENCE                         │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Start coding:       tasks.md (Week 1, Day 1)           │
│  Code examples:      IMPLEMENTATION_GAPS.md             │
│  Daily guide:        QUICK_START_GUIDE.md               │
│  Big picture:        FORWARD_PLAN.md                    │
│  Visual guide:       VISUAL_ROADMAP.md                  │
│  Avoid mistakes:     LESSONS_LEARNED.md                 │
│                                                          │
│  Requirements:       requirements.md                    │
│  Architecture:       design.md                          │
│  Standards:          stackfast-standards.md             │
│  Recent changes:     CHANGELOG.md                       │
│                                                          │
└─────────────────────────────────────────────────────────┘

Ready to start? Open tasks.md and go to Week 1, Day 1! 🚀