Roadmap

Step 2: Check Decisions

Read .claude/docs/DECISIONS.md and count:

• Total decisions
• PROPOSED (pending review)
• ACCEPTED (active)
• HIGH impact decisions

Step 3: Analyze Git Status

git status --short
git branch --show-current
git log --oneline -5

Determine:

• Current branch and its purpose
• Uncommitted changes
• Recent commit activity

Step 4: Scan TODOs in Code

grep -r "TODO\|FIXME\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | head -20

Count and categorize:

• TODO: Features to implement
• FIXME: Bugs to fix
• XXX: Hacky code to refactor

Step 5: Generate Roadmap View

Output Format

📍 PROJECT ROADMAP
═══════════════════════════════════════════════════════════

📊 OVERVIEW
┌─────────────────────────────────────────────────────────┐
│ Features: 5 total │ Decisions: 12 │ TODOs: 8           │
│ 🟢 Done: 2  🟡 In Progress: 1  🔴 Not Started: 2       │
└─────────────────────────────────────────────────────────┘

📋 FEATURES BY STATUS

🔴 NOT STARTED
┌──────────────────────────────────────────────────────────┐
│ P0 │ User Authentication        │ Large  │ APPROVED     │
│ P1 │ Dashboard Analytics        │ Medium │ DRAFT        │
└──────────────────────────────────────────────────────────┘

🟡 IN PROGRESS
┌──────────────────────────────────────────────────────────┐
│ P1 │ Payment Integration        │ Large  │ IN REVIEW    │
│    │ Branch: feature/payments   │ 3 uncommitted files   │
└──────────────────────────────────────────────────────────┘

🟢 COMPLETED
┌──────────────────────────────────────────────────────────┐
│ P0 │ Project Setup              │ Small  │ IMPLEMENTED  │
│ P1 │ User Profile Page          │ Medium │ IMPLEMENTED  │
└──────────────────────────────────────────────────────────┘

⚠️ PENDING DECISIONS
┌──────────────────────────────────────────────────────────┐
│ ADR-005 │ GraphQL vs REST for API │ PROPOSED │ HIGH     │
└──────────────────────────────────────────────────────────┘

🐛 TECHNICAL DEBT
┌──────────────────────────────────────────────────────────┐
│ TODOs: 5 │ FIXMEs: 2 │ XXX: 1                           │
└──────────────────────────────────────────────────────────┘

═══════════════════════════════════════════════════════════

Step 6: Intelligent Next Step Recommendations

Analyze the project state and recommend the single most important next action.

Decision Logic

IF uncommitted changes exist:
    → "Commit or stash your changes first"
    
ELSE IF PROPOSED decisions exist:
    → "Review pending decision: [ADR-XXX]"
    
ELSE IF P0 features are NOT STARTED:
    → "Start critical feature: [Feature Name]"
    → Suggest: "/step-by-step [feature description]"
    
ELSE IF features are IN PROGRESS:
    → "Continue: [Feature Name]"
    → Show branch and remaining work
    
ELSE IF FIXMEs exist:
    → "Fix bugs first: [count] FIXMEs found"
    → Suggest: "/debug [first FIXME location]"
    
ELSE IF P1 features are NOT STARTED:
    → "Start next priority: [Feature Name]"
    
ELSE IF TODOs > 10:
    → "Technical debt: [count] TODOs need attention"
    → Suggest: "/refactor to clean up"
    
ELSE:
    → "All clear! Define new features with /interview"

Next Step Output

🎯 RECOMMENDED NEXT STEP
═══════════════════════════════════════════════════════════

Priority: HIGH
Action: Start implementing User Authentication

Why:
• P0 (Critical) priority feature
• Status: APPROVED (ready to build)
• No blockers or pending decisions

Command:
/step-by-step "Implement user authentication with JWT"

Alternative Actions:
1. Review spec first: cat .claude/docs/specs/user-auth.md
2. Consult architect: @backend-architect design auth API
3. Skip to next: P1 Dashboard Analytics

═══════════════════════════════════════════════════════════

Step 7: Ask for Action (use AskUserQuestion)

After showing roadmap and recommendation:

What would you like to do?
1. Start recommended task
2. View a specific feature spec
3. Add new feature (/interview)
4. Nothing for now

If user selects 1: Trigger the suggested command If user selects 2: Ask which spec and display it If user selects 3: Guide them to /interview

Edge Cases

No specs exist:

📍 PROJECT ROADMAP

No features defined yet.

🎯 RECOMMENDED NEXT STEP
Define your first feature: /interview "describe your feature"

No git repo:

• Skip git status section
• Note: "Not a git repository"

Empty specs folder:

• Create the folder if missing
• Suggest creating first spec

Priority Scoring

When multiple features have same status, rank by:

1. Priority (P0 > P1 > P2 > P3)
2. Effort (Small > Medium > Large for quick wins)
3. Dependencies (features with no blockers first)
4. Age (older specs first to prevent stagnation)

Collaboration

This skill works well with:

• /interview - Define new features
• /step-by-step - Execute recommended tasks
• /debug - Fix FIXMEs
• /refactor - Clean up TODOs
• @product-manager - Reprioritize features
• @tech-lead - Resolve pending decisions