Roadmap visualizer

Roadmap Visualizer

Keeps one canonical roadmap file and turns it into a visual that can be read in seconds. It fights the wall-of-text problem — so it must not reproduce the wall.

Operating principle

ROADMAP.md is the single source of truth — not the chat, not this skill. Every render reads it first. Every agreed change is written back to it immediately. The chat is where the roadmap is discussed; ROADMAP.md is where it lives. These must never drift apart.

---

The canonical file: ROADMAP.md

The skill reads and writes this exact structure so the file stays machine-reliable and human-readable. The status table is the canonical data; the diagram is a generated view of it (regenerated from the table on every change, so they can't disagree).

# Project Roadmap
_Last updated: YYYY-MM-DD · ROADMAP.md is the source of truth for project sequencing._

## Shape
<gated-sequence | time-bound | parallel-streams | decision-tree | status-board>

## Diagram
<mermaid block — a generated VIEW of the Status table below; do not hand-edit>

## Status
| # | Item | Status | Gated on / Next |
|---|------|--------|-----------------|
| 1 | ...  | ✅ Done | — |
| 2 | ...  | 🔄 In flight | ... |
| 3 | ...  | ⏳ Pending | depends on #2 |
| 4 | ...  | ❌ Blocked | blocker: ... |
| 5 | ...  | 🅿️ Parked | ... |

## Constraints / Invariants
- <locked decisions, immutable items, guardrails — omit section if none>

## Amendment log
- YYYY-MM-DD: <what changed and why>

Status legend: ✅ done · 🔄 in flight · ⏳ pending · ❌ blocked · 🅿️ parked

---

Step 1 — Ensure ROADMAP.md exists, then read it

1. Look for ROADMAP.md (project root, or wherever the project keeps it).
2. If it does not exist, create it (see "First run" below) — the roadmap must be a durable file, not chat scrollback.
3. Read it fully before rendering. Render only what it states.

If ROADMAP.md and the recent conversation disagree (common when work happens across more than one channel or session), surface the discrepancy plainly and ask which is current — do not silently pick one, and do not overwrite the file until the user resolves it.

---

Step 2 — Diagnose the roadmap's shape (this picks the diagram)

Record the shape in the ## Shape field. The wrong diagram misrepresents the plan, so choose by what actually drives sequencing:

If the plan is driven by…	…it is a	…render as
dependencies or evidence gates ("X only after Y proves out")	gated sequence	flowchart with gate edges
dates and durations	time-bound plan	Gantt
several tracks progressing in parallel	multi-stream	swimlanes (flowchart LR + subgraphs)
a branching decision ("if A then B else C")	decision tree	flowchart with decision nodes
a simple list of states (todo/doing/done)	status board	table only, no diagram

When ambiguous, ask ONE question before drawing. Never default to a dated Gantt — timelines invent precision that gated sequences don't have.

---

Step 3 — Render (and write back)

On render, output the diagram + status table to the chat. On any change, also update ROADMAP.md: edit the Status table, regenerate the Diagram from it, bump Last updated, and append an Amendment-log line.

Diagram — examples by shape

Gated sequence (flowchart):

flowchart TD
    classDef done fill:#A7D8A7,stroke:#2E7D32,color:#1B3D1B
    classDef active fill:#FFE08A,stroke:#C79100,color:#3D3000
    classDef pending fill:#E0E0E0,stroke:#9E9E9E,color:#333
    classDef blocked fill:#F5C6C6,stroke:#C62828,color:#3D1414

    A["Phase 1"]:::done --> B["Phase 2"]:::active
    B -. "gate: only if<br/>Phase 2 proves out" .-> C["Phase 3"]:::pending

Time-bound plan (Gantt):

gantt
    title Roadmap
    dateFormat YYYY-MM-DD
    section Track
    Phase 1 :done,   p1, 2026-01-01, 2026-01-20
    Phase 2 :active, p2, after p1, 21d
    Phase 3 :        p3, after p2, 14d

Parallel workstreams (swimlanes):

flowchart LR
    subgraph S1 [Stream A]
        A1[Task] --> A2[Task]
    end
    subgraph S2 [Stream B]
        B1[Task] --> B2[Task]
    end

Set each node's status class to match the table. Keep node labels ≤6 words.

Constraints / invariants

If ROADMAP.md carries standing constraints (locked decisions, immutable items, guardrails), echo a short list under the render so they stay visible. Omit if none.

---

/status — compact view

Quick check, no diagram, one screen. Still read from ROADMAP.md:

NOW:     [what's in flight]
DONE:    [recently completed]
NEXT:    [the immediate next action]
GATED:   [what's waiting, and on what]
BLOCKED: [anything stuck, and why]

---

First run — creating ROADMAP.md

If no ROADMAP.md exists when the skill is triggered:

1. Say so: "No ROADMAP.md yet — I'll create one from this discussion."
2. Extract decisions, phases, priorities, and any stated constraints from the conversation (or from a handover/plan doc the user points to).
3. Diagnose the shape (Step 2).
4. Draft ROADMAP.md in the canonical structure above and show it for confirmation.
5. On confirmation, save it. From here on it is the source of truth — the chat and this skill defer to it.

If the project already keeps its roadmap inside another document (e.g. a handover file), recommend migrating it into ROADMAP.md and having the other document reference it — one canonical location, to avoid two roadmaps that drift.

---

Amendment discipline (when the plan changes)

When a decision in conversation changes the roadmap:

1. Show the BEFORE state of only the affected rows.
2. State the change and apply it.
3. Update ROADMAP.md: edit the table, regenerate the diagram, bump Last updated, append an Amendment-log line (YYYY-MM-DD: what changed and why).
4. Re-render to the chat.

Never change the roadmap silently. Never delete rows — mark them 🅿️ parked or cancelled with a reason. Never rephrase a decision differently from how the user stated it.

---

Proactive trigger

Don't always wait to be asked. Offer a refresh when:

• a decision shifts a phase, dependency, or priority,
• an item is confirmed done or newly blocked,
• the discussion has run long without the roadmap in view.

Offer in one line ("That moves Phase 3 — want me to update ROADMAP.md?") and wait for confirmation before writing the file.

---

Rules

• ROADMAP.md is the source of truth; read it first, write changes back every time.
• The status table is canonical; the diagram is a generated view — keep them in sync.
• Match the diagram to the roadmap's shape; never default to a dated Gantt.
• Surface ROADMAP.md-vs-conversation disagreements; don't resolve them silently.
• Keep chat output visual and short — don't reproduce the wall of text.
• This skill visualises and maintains the roadmap. It is not a handoff tool and not a spec/prompt drafter — defer to dedicated skills or processes for those.