git:20260814.769885b to git:20260814.44f11ef

36 added, 16 removed. Audit A to A.

---

name: "Roadmap: Review"

- description: "Interview-led review of the roadmap's health: status freshness, the priorities the graph implies and whether the plan still matches reality"

- when_to_use: "Periodically, or when the roadmap feels stale, the priorities feel off, a milestone dragged past its intent, or the user asks 'is the roadmap still right?'; the strategic complement to roadmap-maintain's mechanical sync."

+ description: "Interview-led review of the roadmap: strategic health (freshness, priorities, milestone integrity) and dependency-graph rationality, in one pass or by lens"

+ when_to_use: "Periodically, or when the roadmap feels stale, priorities feel off, tasks feel blocked for no reason, or a milestone dragged past its intent. Lenses: 'health' for the strategic pass, 'deps' for the edge audit, default both; the judgement complement to roadmap-maintain's mechanical sync."

model: opus

effort: high

metadata:

glyph: ᛟ

family: roadmap

- bundle: roadmap-system

disable-model-invocation: false # explicit: read-only interview that writes nothing itself

allowed-tools: ["Read", "Glob", "Grep", "Bash(python3:*)", "Bash(git log:*)", "Bash(git diff:*)"]

disallowed-tools: ["Edit", "Write", "NotebookEdit"] # writes nothing itself; hands actions to the roadmap-* writers

- arguments: ["milestone"]

- argument-hint: "[milestone id (optional, to scope the review)]"

+ arguments: ["lens", "milestone"]

+ argument-hint: "[health|deps|full] [milestone id (optional)]"

---

# 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, a ready-set whose leverage ordering nobody has looked at since it was authored. This is a guided health check that ends in decisions, not a report that ends in a shrug.

+ `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

- - `.claude/roadmaps.json`: milestone goals, gates, notes, parked (`paused`/`deferred`) tasks

+ - `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)

- Scope to `$ARGUMENTS`'s milestone when given.

- ## Step 2: Assess along four axes

+ ## 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 ("M2 is 85% done with two tasks left, but the last five commits were all M4 territory; deliberate?"). Lead with the highest-stakes findings; skip axes that came back clean. End each round: *"More on this, or shall I pull the findings together?"*

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

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

```text

+ 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

+ ```

+ ```text

→ roadmap-maintain (reconcile): {suspected-done tasks to verify against code}

- → roadmap-maintain (explicit): {status calls: out_of_scope, un-park, re-seed}

- → roadmap-audit-deps: {edges/gates that came up; full audit if several}

- → roadmap-update-tasks: {new tasks surfaced}

+ → 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; turn the review into feature brainstorming (route it); manufacture findings when the roadmap is healthy: "nothing needs changing" is a valid, complete outcome.

+ **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.

<raw-arguments value="$ARGUMENTS" />