Track Roadmap

Track Roadmap

Overview

Maintain ROADMAP.md in the project root as a living, high-level feature plan, so decisions about what to build next are intentional, not reactive. Keep it to features (user-visible capabilities), not tasks — task-level work belongs in track-session. A healthy roadmap is 5-15 committed features readable in under 2 minutes.

Workflow

Every mode runs the same four beats — read the current state, propose a change, confirm with the user, write the file. Only the middle two differ:

Update is the common case: adding an item, marking one done, or logging shipped work all land there. There is no save mode — treat /track-roadmap save as Update. In Update and Audit, edit the affected items in place rather than regenerating the file — ids, ordering, and untouched text survive, and a whole-file rewrite costs more tokens for the same result. Generate is the only mode that writes the file from scratch.

Full per-mode procedures (discovery questions, brainstorm question banks, audit steps): reference/MODES.md.

ROADMAP.md format

---
schema: cc-dash/roadmap@1
project: project-name-here
description: One-line project purpose
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
---

# Roadmap

> Project purpose in one sentence.

## Core Features

<!-- category:core -->

- <!-- id:r_XXXXX status:planned --> **Feature Name** - What it does and why it matters.
- <!-- id:r_XXXXX status:in-progress started:YYYY-MM-DD --> **Feature Name** - Short description.

## Future Ideas

<!-- category:future -->

- <!-- id:r_XXXXX status:idea --> **Feature Name** - Short description.

## Completed

<!-- category:completed -->

- <!-- id:r_XXXXX status:done completed:YYYY-MM-DD --> ~~**Feature Name**~~ - Short description. *(Completed: YYYY-MM-DD)*

Format rules. The cc-dash dashboard parses this file, so a dropped marker silently removes the item from the board:

• Frontmatter requires schema, project, description, last_updated.
• Every item: an id (r_ + 5 random [a-z0-9], permanent — never change) and a status (planned / in-progress / done / idea).
• Every category heading gets <!-- category:slug --> on the next line. Categories themselves are flexible — invent whatever groups fit the project.
• One line per feature: bold title + 1-2 sentence description.

Rules

• The user drives the roadmap — propose changes and wait for confirmation rather than adding, rewording, or removing features on your own judgment.
• High-level only — "User authentication", not "Add bcrypt to hash passwords".
• ROADMAP.md is the source of truth — if it's not in the file, it's not on the roadmap.
• Completed features move, they don't disappear — relocate them to the Completed section with a completed: date instead of deleting, because audits use that history as evidence.

Examples

❌ Bad — - tasks / - lists / - make it look good / - fix bugs: no descriptions, no groupings, mixes features with tasks, no IDs or purpose. The format block above is the ✅ counterpart.

✅ Good — update mode, user says "dark mode shipped yesterday": keep the id, flip the status, add the date, move the line to Completed:

- <!-- id:r_j4t8v status:done completed:2026-03-14 --> ~~**Dark mode**~~ - System-level dark/light theme preference. *(Completed: 2026-03-14)*

Full ✅/❌ comparisons for generate, audit, update, brainstorm, and resume modes: reference/EXAMPLES.md.

Integration

• track-session — after picking a feature, use track-session to plan and track the implementation; SESSION_PROGRESS.md references the ROADMAP item ID.
• Hands-on verification (a playthrough, a parity gate, a release sign-off) is an ordinary roadmap item here — there is no separate checklist file, so nothing files back from one.

Gotchas

• Renaming a feature keeps its id. Edit the title text but leave <!-- id:r_XXXXX --> alone — SESSION_PROGRESS.md roadmap_ref values and cc-dash history both point at it. On a merge, keep the surviving id; on a split, keep the original on one half and generate a new id for the other.
• roadmap_ref can be a list. One session advancing several features writes roadmap_ref: r_abc12,r_def34 — read it as comma-separated, don't assume a single id.
• Resume overwrites an active session plan. If SESSION_PROGRESS.md has uncompleted tasks, ask whether to continue it before presenting the roadmap; switching features replaces that file, so offer /track-session save first.
• Ambiguous audit evidence is Unclear, not a guess. Partial or experimental code (a src/auth/ with no tests) gets surfaced to the user for a ruling rather than being scored Done.
• A 30+ item roadmap is a signal, not a state to preserve. Audit it, move speculative entries to "Future Ideas" as status:idea, and delete what no longer fits — git holds the history, so in-file archiving just adds noise.
• Roadmap drift is expected. When the file stops matching what's being built, run audit to reconcile rather than patching individual lines from memory.

Extended edge cases (codebase-scan noise, brainstorm dead ends, priority paralysis, tightening vague feature descriptions): reference/TROUBLESHOOTING.md.