Track Roadmap

Roadmap tracking activated – I’ll use ROADMAP.md to capture and manage the high-level feature plan for this project.

Overview

Use ROADMAP.md in the project root to plan and track high-level project features. Think through what to build, keep the plan current, and periodically audit whether the roadmap still reflects reality.

Core principle: Maintain a living document of what the project should become, so decisions about what to build next are intentional, not reactive.

Usage Modes

This skill supports three modes via optional arguments:

When to Use

Always use when:

• Starting a new project and need to plan features
• User asks “what should we build?” or “what’s the plan?”
• Project has grown organically and needs direction
• Before a major planning session or milestone

Useful for:

• Capturing feature ideas before they’re lost
• Communicating project scope to collaborators
• Deciding what to work on next
• Tracking what’s been built vs. what’s planned

Avoid when:

• Tracking granular task-level work (use track-session instead)
• Single-feature implementation (just build it)
• Project is a one-off script or throwaway prototype

Mode: Generate

Command: /track-roadmap or /track-roadmap generate

Creates a new ROADMAP.md through an interactive process.

Phase 1: Discovery

Step 1 – Optional codebase scan:

Ask the user if they want a codebase scan to inform the roadmap:

"Would you like me to scan the project to understand what exists before we plan features?"

If yes, examine:

• README.md, CLAUDE.md, or any project description files
• Directory structure and existing features
• TODO/FIXME comments in source files
• Package dependencies (package.json, requirements.txt, etc.)
• Existing issues or task lists

Summarize findings briefly to the user before proceeding.

Step 2 – Interactive questioning:

Ask the user about their vision using AskUserQuestion. Adapt questions to what you learned from the codebase scan (if performed). Core questions:

1. “What is the core purpose of this project?” – Understand the project’s reason to exist.
2. “What are the must-have features you already know about?” – Capture what’s already in the user’s head.
3. “Who is the target user and what workflows should the project support?” – Uncover features the user hasn’t thought of yet.
4. “Are there any technical capabilities you know you’ll need?” – Infrastructure, integrations, platform support, etc.

After gathering answers, propose a draft feature list and ask the user to confirm, add, or remove items before writing ROADMAP.md.

Phase 2: Organize and Write

Group features into logical categories. Write ROADMAP.md using the format below.

Verification before writing:

• User confirmed the feature list
• Features are grouped logically
• Each feature has a clear description (see Format Rules)
• No duplicate or overlapping features

Mode: Update

Command: /track-roadmap update

Modifies an existing ROADMAP.md.

Process

1. Read the current ROADMAP.md
2. Ask the user what changed:
   • New features to add?
   • Features to remove or deprioritize?
   • Features that are now complete?
   • Features that need rewording?
3. Apply changes and present the updated roadmap for confirmation
4. Write the updated ROADMAP.md

Update Rules

• When marking features complete, move them to the “Completed” section
• When adding features, ask which category they belong to
• All rules in the Rules section apply (especially: user confirms all changes)

Mode: Audit

Command: /track-roadmap audit

Performs a combined progress check and relevance review.

Part 1: Progress Check

Scan the codebase to assess each roadmap feature:

• Read project files to determine what’s actually been built
• Compare against ROADMAP.md features
• Categorize each feature:
  • Done – Feature exists and works
  • In Progress – Partially implemented
  • Not Started – No evidence of implementation
  • Unclear – Can’t determine status from code alone

Part 2: Relevance Review

For each feature, ask whether it’s still relevant:

• Present the audit findings to the user
• Ask: “Are there features that are no longer needed?”
• Ask: “Are there new features that should be added?”
• Ask: “Should any priorities change based on what we’ve learned?”

Part 3: Update

Apply any changes from the review and write the updated ROADMAP.md. See the Audit example below for output format.

ROADMAP.md Format

# Roadmap

> Project purpose in one sentence.

## Core Features
- **Feature Name** - Short description of what it does and why it matters.
- **Feature Name** - Short description.

## User Experience
- **Feature Name** - Short description.
- **Feature Name** - Short description.

## Technical Infrastructure
- **Feature Name** - Short description.

## Future Ideas
- **Feature Name** - Short description. (Not committed, just captured.)

## Completed
- ~~**Feature Name**~~ - Short description. *(Completed: YYYY-MM-DD)*

Format Rules

1. Categories are flexible – Use whatever groupings make sense for the project (the above are suggestions)
2. One line per feature – Title in bold + 1-2 sentence description
3. Future Ideas section is a parking lot for uncommitted ideas
4. Completed section preserves history of what’s been built
5. Keep it scannable – The whole file should be readable in under 2 minutes

Rules

1. User drives the roadmap – Never add features without user confirmation
2. Keep it high-level – Features, not tasks. “User authentication” not “Add bcrypt to hash passwords”
3. ROADMAP.md is the source of truth – If it’s not in the file, it’s not on the roadmap
4. Audit regularly – Roadmaps drift. Audit catches the drift.
5. Don’t over-plan – 5-15 features is a healthy roadmap. 50 features means the project needs splitting.
6. Completed features stay – Move to Completed section, don’t delete. History matters.

Examples

Example: Generating a Roadmap

A personal task manager that syncs across devices.

Core Features

• Task CRUD – Create, read, update, and delete tasks with title, description, and due date.
• Task lists – Organize tasks into named lists (e.g., Work, Personal, Shopping).
• Due date reminders – Notify users when tasks are approaching their due date.

User Experience

• Dark mode – Support system-level dark/light theme preference.
• Keyboard shortcuts – Power users can manage tasks without touching the mouse.
• Drag-and-drop reordering – Reorder tasks within and across lists.

Technical Infrastructure

• Cloud sync – Sync tasks across devices via a backend API.
• Offline support – App works without internet, syncs when reconnected.

Future Ideas

• Shared lists – Collaborate on task lists with other users.
• Recurring tasks – Tasks that repeat on a schedule.

Completed

**Why this is good:** Clear project purpose, logical groupings, each feature is one line with a concise description, Future Ideas captures uncommitted work, Completed section ready for use.
</Good>

<Bad>
```markdown
# Roadmap

- tasks
- lists
- dark mode
- sync
- make it look good
- fix bugs
- add tests
- deploy somewhere
- maybe sharing?

Why this is bad: No descriptions, no groupings, mixes features with tasks (“fix bugs”, “add tests”), vague items (“make it look good”), no project purpose, no structure.

Example: Auditing a Roadmap

Progress

Recommendations

• Move “Task CRUD” and “Task lists” to Completed
• “Dark mode” is close – just needs dark theme CSS variables
• Consider deprioritizing “Cloud sync” until core UX is solid
• New: “Search/filter tasks” came up in TODO comments (src/App.tsx:42)

**Why this is good:** Every feature checked, evidence cited with file paths, actionable recommendations, surfaced a new feature from codebase discovery.
</Good>

<Bad>
```markdown
## Audit
Looks like some stuff is done. Maybe we should build more things.

Why this is bad: No specifics, no evidence, no per-feature assessment, no actionable recommendations.

Example: Updating a Roadmap

User says: “We decided not to do offline support, and I want to add calendar integration.”

User Experience

• Dark mode – Support system-level dark/light theme preference.

After (confirmed with user):

Technical Infrastructure

• Cloud sync – Sync tasks across devices via a backend API.

User Experience

• Dark mode – Support system-level dark/light theme preference.
• Calendar integration – Show tasks with due dates in a calendar view.

**Why this is good:** Confirms removal before acting, places new feature in appropriate category with description, only changes what the user asked for.
</Good>

<Bad>
```markdown
# User asked to remove offline support.
# Agent removes offline support AND cloud sync AND dark mode
# because it decided they weren't important either.

Why this is bad: Removed features the user didn’t ask about. Never make unilateral roadmap decisions.

Troubleshooting

Problem: ROADMAP.md has too many features (30+)

Cause: Roadmap has become a wish list instead of a plan.

Solution:

• Run /track-roadmap audit to review relevance
• Move speculative items to “Future Ideas”
• Consider splitting into multiple projects or milestones
• A healthy roadmap has 5-15 committed features

Problem: Roadmap doesn’t match what’s actually being built

Cause: Roadmap wasn’t updated as priorities shifted.

Solution:

• Run /track-roadmap audit to reconcile plan vs. reality
• Update the roadmap to reflect actual direction
• Set a habit: audit after every major feature completion

Problem: Features are too granular

Cause: Mixing task-level work with feature-level planning.

Solution:

• Features should be user-visible capabilities, not implementation steps
• Bad: “Add bcrypt”, “Create user table”, “Build login form”
• Good: “User authentication”
• Use track-session for task-level tracking within a feature

Problem: Codebase scan suggests irrelevant features

Cause: Discovery picked up on implementation details, not user features.

Solution:

• Treat scan results as suggestions, not requirements
• Always confirm with user before adding to roadmap
• Focus on user-facing capabilities, not internal architecture

Problem: User can’t decide on features

Cause: Too many options or unclear project direction.

Solution:

• Start with the core question: “What problem does this project solve?”
• Ask: “If you could only build 3 features, what would they be?”
• Use the “Future Ideas” section as a pressure valve for uncommitted items

Integration

This skill works with:

• track-session – After choosing a feature from the roadmap, use track-session to plan and track the implementation work
• generate-skill – Use the roadmap to identify features that could become reusable skills
• git-worktree – Work on multiple roadmap features in parallel across worktrees

Workflow pattern:

/track-roadmap generate  →  Pick a feature  →  /track-session  →  Build it
/track-roadmap audit     →  Review progress  →  /track-roadmap update  →  Adjust plan

Pairs with:

• Sprint planning and milestone reviews
• Project kickoff and scope definition
• Periodic retrospectives