Roadmap: Review

Roadmap: Review

roadmap-maintain keeps the roadmap consistent; this skill asks whether it's still true. A roadmap can validate clean while quietly rotting: done-in-code tasks still todo, milestone goals describing last quarter's intent, edges that outlived their reason, a ready-set whose leverage ordering nobody has looked at since it was authored. This is a guided check that ends in decisions, not a report that ends in a shrug.

Read-only: findings route to the skills that write. Shared conventions: ~/.claude/library/references/roadmap-conventions.md.

Step 0: Resolve the lens

$lens is health, deps or full (the default when absent). Health runs axes 1 to 4; deps runs axis 5 with its suspect-list machinery; full runs everything. $milestone scopes any lens to one milestone (plus its cross-milestone edges; that is often where the rot is).

Step 1: Gather the evidence

roadmap.py detect guard as usual (exit 3 → roadmap-migrate; exit 2 → ask). Then:

• roadmap.py stats and ready --json: distribution, per-milestone done-%, the ready-set with leverage signals
• roadmap.py graph --json (deps and full lenses): the full edge set
• .claude/roadmaps.json: milestone goals, gates, notes, parked (paused/deferred) tasks, softDependsOn
• git log --oneline -30: what actually shipped recently, as a drift smell-test (full reconciliation belongs to roadmap-maintain reconcile; here it only informs questions)

Step 2: Assess along five axes

1. Freshness: does recent git activity suggest tasks are done-in-code but not marked? Are there blocked tasks whose blockers look finished? (Flag for a reconcile run; don't relitigate evidence here.)
2. Implied priorities: the ready-set is a priority statement: its leverage ordering says what matters next. Does the user agree with what it's saying? A high-leverage candidate nobody intends to touch, or a pet task with zero unblocks being worked first, are both findings.
3. Milestone integrity, per milestone: is the goal sentence still the goal? Is a nearly-done milestone (high done-%) worth closing out before opening a new front? Has any milestone become a dumping ground?
4. The parked and the dead: every paused/deferred task and every gate: still genuinely waiting, or quietly obsolete? Any todo that will realistically never be done and should be out_of_scope?
5. Graph rationality (deps and full lenses): the recompute keeps statuses consistent with the graph; nothing checks the graph itself is right. Edges accrete: a dependency that made sense at authoring time survives long after the reason evaporated, and a missing edge never announces itself. Build the suspect list mechanically before asking anything, so the interview spends the user's attention only where the graph is genuinely questionable:
   • Suspicious hard edges: a dependsOn between tasks that share no obvious artefact (different area, different category, no note explaining it). Candidate for removal or demotion to softDependsOn.
   • Suspicious absences: task pairs that plainly touch the same artefact (matching terms in descriptions/notes) with no edge either way.
   • Over-serialised chains: A→B→C→D where the middle links look like authoring order, not real dependency; each unnecessary link delays the tail.
   • Bottlenecks: a task whose transitiveUnblocks dwarfs the rest; is the fan-in real, or are several dependants only loosely related to it?
   • Gate rationality: for every external gate, is it still genuinely external, still imposing the right status, and is its blocks[] list still the honest set?
   • Milestone boundaries: tasks whose edges mostly cross into a different milestone probably live in the wrong one; milestone-ID dependencies (M1) worth checking against intent (all of M1, or really just two tasks in it?).
   • Soft/hard misfiles: softDependsOn entries that in truth gate the work, and hard edges that are really "nice to sequence".

Step 3: The interview

2–4 questions per round, each anchored to a specific observation with its evidence inline ("M2 is 85% done with two tasks left, but the last five commits were all M4 territory; deliberate?", "3IN.2 depends on 2EV.4, but nothing in either description links them; what's the connection?"). Lead with the highest-stakes findings; skip axes that came back clean; never present the whole suspect list as homework.

For each graph finding the user engages with, converge on one of: keep (reason now recorded for the notes field), remove, demote to soft, promote to hard, add missing edge, move task to another milestone, gate edit. End each round: "More on this, or shall I pull the findings together?"

Step 4: Findings and routing

Present decisions made, grouped by the skill that executes them. Edge changes use this shorthand:

Edge removals:    {task} -x-> {dep}   ({why})
Edge additions:   {task} ---> {dep}   ({why})
Soft/hard flips:  {task} ~~~> {dep}   ({direction and why})
Gate edits:       {gateId}: {change}
Moves:            {task} → {milestone} ({why})
Note updates:     {task}: record kept-edge rationale

→ roadmap-maintain (reconcile):  {suspected-done tasks to verify against code}
→ roadmap-maintain (explicit):   {status calls, edge and gate edits from the shorthand above}
→ roadmap-update-tasks:          {new tasks surfaced; milestone moves}
→ roadmap-create-interview:      {a theme big enough to deserve its own session}
→ No action:                     {reviewed and healthy; say so explicitly}

Offer to run the first of these now. This skill writes nothing itself.

When the findings are substantial or worth sharing, also offer to render them visually: map them to artefact-audit's JSON shape and run that skill in render-only mode. Decline gracefully if the terminal summary is all that's wanted.

Red flags

Never: edit any roadmap artefact directly; mark anything done without roadmap-maintain's evidence gate; propose removing an edge just because it's inconvenient (the question is whether it's true); treat a user's "I don't remember why" as licence to delete: an unexplained edge that keeps coming up gets a note, not a silent removal; turn the review into feature brainstorming (route it); manufacture findings when the roadmap is healthy: "nothing needs changing" is a valid, complete outcome.