---
name: roadmap
description: "When the user invokes /roadmap commands, manage ROADMAP.md as a living development journal. Track milestones, log progress, and maintain a searchable history of what was learned."
---

# Roadmap Skill

When the user invokes `/roadmap` commands, you are managing a **living development journal** stored in `ROADMAP.md`. This file serves as both a task list and a chronological record of development progress.

## Core Principles

1. **ROADMAP.md is the source of truth** - All task definitions, status, and journal entries live here
2. **Milestones are headings** - Each `### X.Y` heading is a milestone identifier
3. **Checkboxes track status** - `[ ]` = not started, `[x]` = complete
4. **Journal entries are indented** - Added as nested list items under milestones
5. **You modify ROADMAP.md directly** - Use `read`, `edit`, or `write` tools as appropriate

## Milestone Identification

A milestone is any level-3 heading (`###`) or deeper that starts with a number pattern:
- Valid: `### 1.1 Analyze Architecture`, `#### 1.2.1 Subtask`
- Invalid: `### Introduction`, `### Phase 1` (no number)

The milestone ID is the number part: `1.1`, `1.2.1`, etc.

## Journal Entry Format

Journal entries are appended under their milestone as indented list items with these prefixes:

```markdown
- **Journal**: [timestamp] - [message]
- **Time**: [elapsed minutes]
- **Blockers**: [what's preventing progress]
- **Decision**: [rationale for choices]
- **Tau Notes**: [observations about Tau's capabilities]
- **Lesson**: [general development learning]
```

Always include a timestamp in `YYYY-MM-DD HH:MM` format for Journal entries.

## Commands

### `/roadmap` or `/roadmap status`
Show a compact status summary:
1. Read `ROADMAP.md`
2. Count total milestones (level-3+ headings matching number pattern)
3. Count completed milestones (checkbox is `[x]`)
4. Calculate percentage: `(completed / total) * 100`
5. List the next 3 incomplete milestones by ID order

Format:
```
Roadmap Progress: 2/17 (11.76%)
Next:
  1.3 Add Configuration File Support
  2.1 Add Type Hints
  2.2 Create Unit Tests
```

### `/roadmap view`
Display the full contents of `ROADMAP.md` using the `read` tool.

### `/roadmap view [milestone-id]`
1. Find the milestone heading matching `[milestone-id]`
2. Display that heading and all its content (tasks + journal entries)

### `/roadmap next`
1. Find all milestones with `[ ]` status
2. Sort by milestone ID (natural sort: 1.1 < 1.2 < 1.10 < 2.1)
3. Show the first one with its description

Format:
```
Next milestone: 1.3 Add Configuration File Support
Description: Use Tau to add TOML-based configuration
Prompt: "Add support for a ~/.config/peak-monitor.toml configuration file..."
```

### `/roadmap complete [milestone-id]`
1. Find the milestone with ID `[milestone-id]`
2. Change its checkbox from `[ ]` to `[x]`
3. Prompt the user: "Enter journal notes (or 'skip'): "
4. If user provides text, append it as a Journal entry with timestamp
5. Use `edit` tool to modify ROADMAP.md

### `/roadmap journal [milestone-id] [message]`
1. Find the milestone with ID `[milestone-id]`
2. Append a new journal entry under it with current timestamp
3. Format: `- **Journal**: YYYY-MM-DD HH:MM - [message]`
4. Use `edit` tool to add the line

### `/roadmap start [milestone-id]`
1. Find the milestone
2. Record the start time (store in memory for this session)
3. Reply: "Started milestone [milestone-id]. Timer running..."

### `/roadmap stop [milestone-id]`
1. Calculate elapsed time since start
2. Append a Time entry: `- **Time**: [minutes]min`
3. Clear the timer for this milestone

### `/roadmap search [query]`
1. Read ROADMAP.md
2. Find all journal entries (lines starting with `- **Journal**`, `- **Tau Notes**`, etc.)
3. Filter entries containing [query] (case-insensitive)
4. Display matching entries with their milestone ID

Format:
```
Found 2 matches:
  1.1: 2026-07-11 14:32 - Noticed that GTK initialization needs error handling
  1.3: 2026-07-11 15:01 - Tau successfully added config file support
```

### `/roadmap add [description]`
1. Find the highest existing milestone ID
2. Increment it (1.1 -> 1.2, 1.9 -> 1.10, 2.1 -> 2.2)
3. Append a new milestone at the end of the file:
   ```markdown
   
   ### [new-id] [first line of description]
   - [ ] [full description]
   ```

### `/roadmap blockers`
1. Find all milestones with Blockers entries
2. Display each with its blocker notes

Format:
```
Blocked milestones:
  3.2 CLI Mode
    - **Blockers**: Requires refactoring from 1.2 to be complete first
  4.3 Systemd Service
    - **Blockers**: Need to understand systemd user services better
```

## File Location

Always look for `ROADMAP.md` in the current working directory. If not found:
1. Check parent directories up to project root
2. If still not found, reply: "No ROADMAP.md found. Would you like me to create one?"

## Error Handling

- If milestone ID not found: "Milestone [id] not found. Use /roadmap view to see available milestones."
- If command invalid: "Unknown roadmap command. Available: status, view, next, complete, journal, start, stop, search, add, blockers"
- If file write fails: Report the error and suggest manual edit

## Integration with Development Workflow

When a milestone involves using Tau to complete a task:
1. The milestone should include a **Prompt** field with the exact prompt to use
2. After completing the task via Tau, use `/roadmap complete` to mark it done
3. Add journal entries documenting:
   - What Tau did well
   - What Tau struggled with
   - What you had to do manually
   - Lessons learned about prompting Tau

## Example Session

```
User: /roadmap next

You: (read ROADMAP.md, find first [ ] milestone)
Next milestone: 1.1 Analyze Current Architecture
Description: Use Tau to analyze peak_monitor.py and identify structural improvements
Prompt: "Analyze peak_monitor.py and suggest a better project structure. Do not implement yet."

User: /roadmap start 1.1

You: (record start time)
Started milestone 1.1. Timer running...

User: (user works with Tau on the task...)

User: /roadmap journal 1.1 "Tau successfully parsed the GTK code and identified 3 structural issues"

You: (append to ROADMAP.md)
- **Journal**: 2026-07-11 14:32 - Tau successfully parsed the GTK code and identified 3 structural issues

User: /roadmap stop 1.1

You: (calculate elapsed, append Time entry)
- **Time**: 23min

User: /roadmap complete 1.1

You: (change [ ] to [x], prompt for final notes)
Milestone 1.1 completed!
Enter journal notes (or 'skip'): 

User: The analysis revealed we need to separate GUI from core logic

You: (append final journal entry)
- **Journal**: 2026-07-11 14:55 - The analysis revealed we need to separate GUI from core logic
- **Decision**: Will refactor into config, core, and gui modules
```

## Remember

- Always read ROADMAP.md before modifying it
- Always use the exact milestone ID from the heading
- Always include timestamps in Journal entries
- Always preserve existing content
- Never delete or reorder milestones without explicit user request