π« Toolkit to help you get started with SDD or any other process!
docs(concepts): document the spec-of-specs feature breakdown approach (#3648)
Manfred Riembb5a2c54241c
diff --git a/docs/concepts/complex-features.md b/docs/concepts/complex-features.mdindex 10e814ba1..4fe9ae85d 100644--- a/docs/concepts/complex-features.md+++ b/docs/concepts/complex-features.md@@ -63,10 +63,14 @@ independently specified sub-features. Each sub-feature gets its own`spec.md`, `plan.md`, and `tasks.md`, and runs through its ownspecify/plan/tasks/implement cycle.-This is the "spec of specs" approach: the first iteration breaks a massive-feature into smaller, self-contained specs that can each be implemented without-overwhelming the model. It adds the most overhead, so reserve it for features-that are too large to handle any other way.+This is the "spec of specs" approach: a first pass breaks a massive feature into+smaller, self-contained specs that can each be implemented without overwhelming the+model. It adds the most overhead, so reserve it for features that are too large to+handle any other way.++See [Spec of Specs](spec-of-specs.md) for the full procedure β how to run the+roadmap pass, structure the roadmap artifact, link sub-specs back to it, and a worked+example.## Which Approach to Choosediff --git a/docs/concepts/spec-of-specs.md b/docs/concepts/spec-of-specs.mdnew file mode 100644index 000000000..2439798e0--- /dev/null+++ b/docs/concepts/spec-of-specs.md@@ -0,0 +1,171 @@+# Spec of Specs++When a feature is too large to run through a single+`/speckit.specify` β `/speckit.plan` β `/speckit.tasks` β `/speckit.implement`+cycle without the model losing track mid-implementation, you can break it into a+**roadmap** of smaller, independently-specified sub-features. This is the "spec of+specs" approach: one up-front pass decomposes a massive feature into self-contained+specs, and each of those runs through its own specify/plan/tasks/implement cycle.++> **When to reach for this.** Decomposition adds the most overhead of any strategy+> in [Handling Complex Features](complex-features.md). Use it **only when the lighter+> options there are insufficient** β first try limiting how many tasks run per+> `/speckit.implement` invocation, then sub-agent delegation, then a combination.+> Reach for a spec of specs only when even a single phase is too large to handle in+> one run.++The rest of this page describes *how* to do it with the tools you already have. No+new commands or extensions are required.++## The roadmap pass++Before writing any sub-spec, do a single decomposition pass to produce a roadmap.+Treat this as a lightweight planning conversation with your agent, not a full spec:++1. **State the whole feature.** Describe the large feature (the "epic") in a+ sentence or two so the agent has the full picture up front.+2. **Identify independent slices.** Ask the agent to propose a small set of+ sub-features that each deliver a coherent piece of the epic and can be specified+ on their own. Aim for slices that are independently testable β implementing just+ one should leave you with something demonstrable.+3. **Draw the boundaries.** For each slice, write one line of intent and an explicit+ scope boundary (what is in, what is deferred to a sibling slice). Sharp+ boundaries are what keep each sub-spec small enough to fit in context.+4. **Order by dependency.** Note which slices depend on others and sequence them so+ prerequisites come first. Slices with no dependency on each other can be built in+ any order. To build independent slices in parallel, use separate worktrees so each+ run has isolated active-feature state.+5. **Record the result as a roadmap.** Capture the slices in a durable roadmap file+ (below) so every later sub-spec can point back to it.++The roadmap is deliberately shallow: it names and orders the sub-features but does+**not** design them. The design happens when each slice runs through its own+`/speckit.specify`.++## The roadmap artifact++The roadmap is an ordinary Markdown file you author and keep under version control β+there is no special tooling behind it. Put it where the sub-specs can find it:++- For a feature-scoped epic: `specs/<epic-slug>/roadmap.md`.+- For a larger, cross-cutting epic: a top-level `ROADMAP.md`.++Each roadmap entry carries a stable id (used later for linking), a name, its intent,+its scope boundary, its dependencies, a status, and β once the sub-spec exists β a+link to it. A minimal template:++```markdown+# Roadmap: <epic name>++<One or two sentences: what the epic is and why it is being decomposed.>++**Status legend**: planned Β· in-progress Β· done++| ID | Sub-feature | Intent | Scope boundary | Depends on | Status | Sub-spec |+|----|-------------|--------|----------------|-----------|--------|----------|+| R1 | <name> | <one line> | <in / deferred> | β | planned | β |+| R2 | <name> | <one line> | <in / deferred> | R1 | planned | β |+| R3 | <name> | <one line> | <in / deferred> | R1 | planned | β |+```++Keep the `ID` column immutable once a sub-spec references it β it is the anchor for+traceability. Fill in the `Sub-spec` column with the path to each sub-feature's spec+directory as you create it, and update `Status` as work progresses.++## Specifying each sub-feature++With the roadmap in hand, work through the entries one at a time using the normal+Spec Kit flow β nothing new to learn:++1. Pick the next roadmap entry whose dependencies are already `done` (or have none).+2. Run `/speckit.specify` for just that slice, describing only its intent and scope+ from the roadmap entry. Because the slice is bounded, its spec, plan, and tasks+ stay well within the context window.+3. Run `/speckit.plan`, `/speckit.tasks`, and `/speckit.implement` for that slice as+ usual.+4. Mark the roadmap entry `done` and move to the next one.++Each slice is a complete, independent Spec Kit feature with its own+`spec.md`/`plan.md`/`tasks.md`. The roadmap is what ties them together.++## Linking sub-specs to the roadmap++To keep scope and intent from drifting across separate runs, every sub-spec+references its roadmap entry, and the roadmap links back β a simple, greppable,+bidirectional convention:++- **Sub-spec β roadmap.** In the sub-feature's `spec.md`, name the parent roadmap+ and entry id in the `Input` / summary line, for example:++ ```markdown+ **Input**: Parent roadmap: `specs/<epic>/roadmap.md` β entry **R3**. <feature description>+ ```++- **Roadmap β sub-spec.** In the roadmap table, set the entry's `Sub-spec` column to+ the sub-feature's directory, e.g. `specs/<epic>-part-3/`.++Because both directions are plain text, you can trace any sub-spec back to its place+in the epic (and find its siblings) with a quick search β no tooling, no metadata+schema.++## Keeping the roadmap and sub-specs in sync++The roadmap is a living document. As you learn more, keep it and the sub-specs+aligned:++- **Roadmap first, then reconcile.** When scope shifts, update the roadmap entry+ first, then update any sub-specs it affects. The roadmap is the source of truth for+ how the epic is divided.+- **Respect dependencies and ordering.** If a slice depends on another, build the+ prerequisite first and cross-reference the dependent sub-spec so the relationship+ is visible from both sides.+- **Recurse when a slice is still too big.** If a sub-feature turns out to be too+ large to specify in one cycle, give it its own roadmap and decompose it further β+ the same approach applies one level down. Recursion adds overhead, so only go as+ deep as the context problem actually requires.++## Worked example++Suppose the epic is **"Add a self-service billing portal"** β far too large for a+single cycle. The roadmap pass breaks it into three independently-specifiable+slices.++`specs/billing-portal/roadmap.md`:++```markdown+# Roadmap: Self-service billing portal++Let customers view invoices, manage payment methods, and change plans without+contacting support. Too large for one cycle, so it is split into independent slices.++**Status legend**: planned Β· in-progress Β· done++| ID | Sub-feature | Intent | Scope boundary | Depends on | Status | Sub-spec |+|----|--------------------|------------------------------------------|---------------------------------------------|-----------|---------|----------|+| R1 | Invoice history | Customers view and download past invoices | Read-only; no payment actions | β | done | specs/billing-invoices/ |+| R2 | Payment methods | Add, remove, and set a default card | No plan changes; assumes invoices exist | R1 | in-progress | specs/billing-payment-methods/ |+| R3 | Plan changes | Upgrade/downgrade the subscription plan | Uses R2's default payment method | R1, R2 | planned | β |+```++Each slice is then specified on its own. For example, the **R2** sub-feature's+`spec.md` opens with a back-reference:++```markdown+# Feature Specification: Billing β payment methods++**Input**: Parent roadmap: `specs/billing-portal/roadmap.md` β entry **R2**.+Let customers add, remove, and set a default payment method in the billing portal.+```++From here a reader can trace **R2** back to the roadmap, see that it depends on+**R1** (invoice history, already `done`), and see that **R3** (plan changes) is+waiting on it. Building R1, then R2, then R3 keeps every run small while the roadmap+preserves the shape of the whole epic.++## For automation (optional)++If you would rather automate roadmap capture and consistency checks than maintain+the file by hand, the community-maintained+[Spec Roadmap extension](https://github.com/srobroek/speckit-roadmap) explores that+direction. It is a third-party extension and is not required β the manual convention+above is enough on its own.diff --git a/docs/toc.yml b/docs/toc.ymlindex 3f3255cdc..a2e07b270 100644--- a/docs/toc.yml+++ b/docs/toc.yml@@ -55,6 +55,8 @@href: concepts/spec-persistence.md- name: Handling Complex Featureshref: concepts/complex-features.md+ - name: Spec of Specs+ href: concepts/spec-of-specs.md# Development workflows- name: Development