taupocket/skills/roadmap/SKILL.md

name	description
roadmap	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:

- **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:

   
   ### [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