roadmap

# Roadmap Skill

Plan project execution by creating milestones and organizing PRDs into an executable queue.

## Workspace Mode Note

When running in workspace mode, all paths are relative to `.aha-loop/` directory:
- Vision analysis: `.aha-loop/project.vision-analysis.md`
- Architecture: `.aha-loop/project.architecture.md`
- Roadmap: `.aha-loop/project.roadmap.json`
- PRD files: `.aha-loop/tasks/`

The orchestrator will provide the actual paths in the prompt context.

---

## The Job

1. Read `project.vision-analysis.md` and `project.architecture.md`
2. Decompose project into milestones
3. Break each milestone into PRDs
4. Order PRDs by dependencies
5. Output `project.roadmap.json`
6. Generate initial PRD files in `tasks/`

---

## Milestone Strategy

### Standard Milestone Structure

| Milestone | Focus | Goal |
|-----------|-------|------|
| **M0: Foundation** | Project scaffolding, CI/CD, tooling | Development environment ready |
| **M1: MVP** | Core features only | Minimal usable product |
| **M2: Essential** | Important features | Feature-complete for basic use |
| **M3: Enhanced** | Nice-to-have features | Polished product |
| **M4: Optimization** | Performance, UX polish | Production-ready |

### Milestone Sizing

Each milestone should:
- Be completable in a reasonable timeframe
- Have 3-7 PRDs (avoid too many or too few)
- Deliver tangible, testable value
- Build on previous milestones

---

## PRD Decomposition

### From Features to PRDs

For each milestone, break down features into PRDs:

```
Milestone: M1 - MVP
├── PRD-001: Project Scaffolding
├── PRD-002: Database Schema
├── PRD-003: Core Data Models
├── PRD-004: Basic API Endpoints
└── PRD-005: Minimal UI
```

### PRD Sizing

Each PRD should:
- Take 1-5 Aha Loop iterations (5-25 stories)
- Focus on one coherent feature area
- Be independently testable
- Not depend on unfinished PRDs

### PRD Ordering

Order PRDs by dependencies:

1. **Infrastructure first** - Project setup, database, auth
2. **Backend before frontend** - APIs before UI that uses them
3. **Core before optional** - Must-have before nice-to-have
4. **Data before presentation** - Models before views

---

## Roadmap JSON Structure

```json
{
  "version": 1,
  "projectName": "[From vision]",
  "status": "in_progress",
  "currentMilestone": "M1",
  "currentPRD": "PRD-002",
  "createdAt": "[timestamp]",
  "updatedAt": "[timestamp]",
  "milestones": [
    {
      "id": "M0",
      "title": "Foundation",
      "description": "Project setup and development environment",
      "status": "completed",
      "completedAt": "[timestamp]",
      "prds": [
        {
          "id": "PRD-001",
          "title": "Project Scaffolding",
          "description": "Initialize project structure, dependencies, and tooling",
          "status": "completed",
          "prdFile": "tasks/prd-scaffolding.md",
          "stories": 5,
          "completedAt": "[timestamp]"
        }
      ]
    },
    {
      "id": "M1",
      "title": "MVP",
      "description": "Minimum viable product with core functionality",
      "status": "in_progress",
      "prds": [
        {
          "id": "PRD-002",
          "title": "Database Schema",
          "description": "Design and implement database schema",
          "status": "in_progress",
          "prdFile": "tasks/prd-database.md",
          "stories": 8,
          "dependsOn": ["PRD-001"]
        },
        {
          "id": "PRD-003",
          "title": "Core API",
          "description": "Implement core API endpoints",
          "status": "pending",
          "prdFile": "tasks/prd-core-api.md",
          "stories": 12,
          "dependsOn": ["PRD-002"]
        }
      ]
    },
    {
      "id": "M2",
      "title": "Essential Features",
      "description": "Complete essential features for basic use",
      "status": "pending",
      "prds": []
    }
  ],
  "changelog": [
    {
      "timestamp": "[timestamp]",
      "action": "created",
      "description": "Initial roadmap created from vision and architecture"
    }
  ]
}
```

---

## Roadmap Creation Process

### Step 1: Analyze Requirements

From vision analysis, categorize features:

```markdown
## Feature Categories

### M1: MVP (Must ship)
- [Feature 1]
- [Feature 2]

### M2: Essential (Should ship)
- [Feature 3]
- [Feature 4]

### M3: Enhanced (Nice to ship)
- [Feature 5]
```

### Step 2: Create M0 Foundation

Every project starts with M0:

```markdown
## M0: Foundation PRDs

### PRD-001: Project Scaffolding
- Initialize project with chosen tech stack
- Set up directory structure
- Configure linting and formatting
- Set up basic CI (if applicable)
- Create initial README

### PRD-002: Development Environment
- Database setup (if applicable)
- Environment configuration
- Development scripts
- Basic testing infrastructure
```

### Step 3: Decompose Milestones into PRDs

For each milestone after M0:

1. List all features for this milestone
2. Group related features
3. Order by dependencies
4. Create PRD for each group
5. Estimate stories per PRD

### Step 4: Generate PRD Files

For each PRD, create a stub file in `tasks/`:

```markdown
# PRD: [Title]

**ID:** PRD-XXX
**Milestone:** M[N]
**Status:** Pending

## Overview

[Brief description from roadmap]

## Context

[How this relates to previous PRDs and the overall project]

## Goals

- [Goal 1]
- [Goal 2]

## User Stories

[To be generated when this PRD becomes active]

## Dependencies

- PRD-XXX: [What it depends on]

## Acceptance Criteria

- [ ] [High-level criterion]
- [ ] [Another criterion]

---

*This PRD will be fully expanded when it becomes the active PRD.*
```

---

## Dynamic Roadmap Updates

### When to Update Roadmap

The roadmap should be updated when:

1. **PRD Completed** - Mark as complete, update timestamps
2. **New Requirement Discovered** - Add new PRD
3. **Scope Change** - Modify or remove PRDs
4. **Better Approach Found** - Restructure PRDs
5. **Milestone Complete** - Update status, move to next

### Update Process

```json
{
  "changelog": [
    {
      "timestamp": "2026-01-29T12:00:00Z",
      "action": "prd_completed",
      "prdId": "PRD-002",
      "description": "Database schema implemented"
    },
    {
      "timestamp": "2026-01-29T14:00:00Z",
      "action": "prd_added",
      "prdId": "PRD-007",
      "description": "Added caching layer PRD based on performance research"
    }
  ]
}
```

### Automatic Triggers

The orchestrator should trigger roadmap review:

- After each PRD completion
- After each milestone completion
- When significant learnings are recorded
- When errors repeatedly occur

---

## Integration with Orchestrator

### Orchestrator Reads

```bash
# Get current PRD
jq '.currentPRD' project.roadmap.json

# Get PRD file path
jq -r '.milestones[].prds[] | select(.id == "PRD-002") | .prdFile' project.roadmap.json
```

### Orchestrator Updates

After PRD completion:

```bash
# Update PRD status
jq '.milestones[].prds[] |= if .id == "PRD-002" then .status = "completed" else . end' project.roadmap.json
```

---

## PRD Queue Management

### Getting Next PRD

```python
# Pseudocode for finding next PRD
def get_next_prd(roadmap):
    for milestone in roadmap.milestones:
        if milestone.status == "completed":
            continue
        for prd in milestone.prds:
            if prd.status == "pending":
                if all_dependencies_complete(prd):
                    return prd
    return None  # All complete or blocked
```

### Handling Blocked PRDs

If a PRD's dependencies aren't met:
1. Skip to next available PRD
2. If no PRDs available, report blocking issue
3. Consider if dependencies need reprioritization

---

## Example Roadmap

**Project:** Personal Finance Tracker (from vision example)

```json
{
  "version": 1,
  "projectName": "Finance Tracker",
  "status": "in_progress",
  "currentMilestone": "M0",
  "currentPRD": "PRD-001",
  "milestones": [
    {
      "id": "M0",
      "title": "Foundation",
      "status": "in_progress",
      "prds": [
        {
          "id": "PRD-001",
          "title": "SvelteKit Project Setup",
          "description": "Initialize SvelteKit project with TypeScript, Tailwind, PWA support",
          "status": "in_progress",
          "prdFile": "tasks/prd-project-setup.md",
          "stories": 6
        }
      ]
    },
    {
      "id": "M1",
      "title": "MVP - Core Expense Tracking",
      "status": "pending",
      "prds": [
        {
          "id": "PRD-002",
          "title": "Data Layer",
          "description": "Implement IndexedDB with Dexie for expense storage",
          "status": "pending",
          "prdFile": "tasks/prd-data-layer.md",
          "stories": 8,
          "dependsOn": ["PRD-001"]
        },
        {
          "id": "PRD-003",
          "title": "Quick Expense Entry",
          "description": "Fast expense input form (< 5 seconds goal)",
          "status": "pending",
          "prdFile": "tasks/prd-expense-entry.md",
          "stories": 10,
          "dependsOn": ["PRD-002"]
        },
        {
          "id": "PRD-004",
          "title": "Expense List View",
          "description": "View and manage recorded expenses",
          "status": "pending",
          "prdFile": "tasks/prd-expense-list.md",
          "stories": 8,
          "dependsOn": ["PRD-002"]
        }
      ]
    },
    {
      "id": "M2",
      "title": "Reports & PWA",
      "status": "pending",
      "prds": [
        {
          "id": "PRD-005",
          "title": "Monthly Reports",
          "description": "Auto-generated monthly expense reports",
          "status": "pending",
          "prdFile": "tasks/prd-reports.md",
          "stories": 10,
          "dependsOn": ["PRD-003", "PRD-004"]
        },
        {
          "id": "PRD-006",
          "title": "PWA Offline Support",
          "description": "Full offline capability with service worker",
          "status": "pending",
          "prdFile": "tasks/prd-pwa.md",
          "stories": 8,
          "dependsOn": ["PRD-002"]
        }
      ]
    }
  ]
}
```

---

## Checklist

Before completing roadmap:

- [ ] All milestones defined with clear goals
- [ ] PRDs created for at least M0 and M1
- [ ] Dependencies between PRDs mapped
- [ ] PRD stub files created in tasks/
- [ ] Roadmap JSON validates
- [ ] Current milestone and PRD set correctly
- [ ] Changelog initialized
- [ ] Saved to `project.roadmap.json`