Writing Roadmaps

Overview

A roadmap turns one oversized idea into a persistent, checkpointed decomposition: a document with checkable steps, each step small enough to ship independently without leaving the app broken, each step traceable to a ticket. It is not a bigger spec — a spec describes one coherent change; a roadmap describes an ordered sequence of changes and the state between them.

REQUIRED BACKGROUND: superpowers:brainstorming — this skill reuses its dialogue discipline (one question at a time, propose 2-3 approaches, incremental section-by-section approval) and its native-Plan-Mode requirement. Read it first; this skill only covers what's different for a multi-step decomposition. Storage/naming (where the roadmap, the feature-level PRD, and each step's own PRD/spec/plan live) is governed by roadmap-conventions — read it before writing anything to disk.

When to Use

• User explicitly says "roadmap" / "дорожная карта", or describes a task spanning multiple releases/weeks/independent deployable chunks.
• The work has a target end-state, but getting there safely requires an ordered sequence of intermediate states, each one shippable on its own.

Not for: a task that fits one spec+plan cycle, even a large one — if there's no requirement that intermediate states be independently shippable, it's not a roadmap, it's a big plan. Use brainstorming → writing-plans directly.

Core Principle: Every Step Must Leave the App Working

The one rule a roadmap adds on top of an ordinary decomposition: after any single step merges, the app builds and runs — no broken imports, no half-migrated types, no dangling references. This is what separates a roadmap step from an arbitrary chunk of a big diff. When ordering steps, ask "if we shipped only steps 1..N and stopped here, is the app in a valid state?" for every prefix. If the honest answer is no, steps are cut wrong — merge them or reorder, don't ship a broken intermediate.