vertical-slices

name

vertical-slices

description

Cut a service (or task) into atomic vertical slices — the spine of the planning pipeline. Use right after requirements-intake (FRD + high-level plan exist) and BEFORE specs/design: each slice is one end-to-end path through all layers, tied to exactly one external input, demoable on its own, dependency-ordered. Out — a slice backlog that each downstream stage (use case, OpenAPI/AsyncAPI, component tests, program-design) consumes one slice at a time. Do NOT use to design a slice's module tree (that is program-design) or to write code. Tier-agnostic, built for weaker tiers: rules, a granularity table, checklists, STOP rules.

vertical-slices.skill — cut a service into atomic vertical slices

Purpose

In: the FRD from requirements-intake (problem statement, Cockburn use cases, interfaces, draft contract + failure-mode map) and the high-level work plan. Out: a slice backlog .agent/planner/slices.md — the ordered list of atomic vertical slices that the rest of the pipeline (docs/04_PLANNING_PIPELINE.md) processes one slice at a time.

This is stage 1. It decides what the slices are, not how a slice is built — the module tree, contracts and unit tests of a slice are program-design (stages 8–10).

Scope

DO:

• Decompose the whole service/task into a list of slices.
• Tie each slice to exactly one external input (one entry point).
• Order slices by dependency; iterate granularity with the operator.

DON'T:

• Design module trees, contracts, or pseudocode (that is program-design).
• Write OpenAPI/AsyncAPI, use cases, tests, or code (later stages / their skills).
• Put detailed file lists or code snippets into a slice (those go stale). But the slice's package root internal/<slug>/ is stable = the slice's identity — declare it (see Owns package: below). Designing the module tree inside that root is program-design, not the slicer.

Vertical-slice rules (hard)

• End-to-end, not a layer. A slice cuts through ALL layers (input → logic → I/O → output), never a horizontal slice of one layer.
• One external input = one slice = one Request. A slice corresponds to exactly one entry point (one HTTP operation / one consumed message). A flag/option is a field of that input, not a new slice. (Same invariant program-design enforces at Step 3 — keep them aligned.)
• NOT a slice (hard list). These are outcomes/framework/boot/ticket-types of the SAME request — never their own slice: error outcomes (4xx/5xx), method-not-allowed (405), unknown-route (404), config/startup/fail-fast (boot), internal-error (500), and scaffold (that is a ticket type, not a slice). Anti-example (WRONG): slice-service-scaffold, slice-method-not-allowed, slice-unknown-route, slice-config-fail-fast. Rule: #slices ≤ #operations (one endpoint → at most one slice; the gate validate-slices.mjs enforces ≤). One endpoint → exactly one slice; the rest are Extensions/framework/boot. The deterministic gate validate-slices.mjs (#slices ≤ #operations + pseudo-slice names) rejects over-decomposition — prose "these are distinct inputs" does NOT override it.
• Demoable alone. A finished slice is verifiable on its own (its component tests can go green independently).
• No orphan value. Every slice delivers a narrow but complete path a user/consumer can exercise.

Steps

Step	Does	Out
1	Confirm input (FRD + high-level plan present; else STOP → requirements-intake)	verified input
2	List external inputs of the service (endpoints + consumed messages)	input list
3	Map each external input to one slice; name it + its bounded context in glossary terms	draft slices
4	Order slices by dependency (blockers first)	ordered list
5	Quiz the operator on granularity + dependencies; iterate to approval	approved backlog
6	Write .agent/planner/slices.md by the template below	slice backlog

Step 5 — operator quiz (present as a numbered list)

For each slice show: Title, Blocked by, Use case(s) covered. Ask:

• Granularity right? (too coarse / too fine)
• Dependencies correct?
• Merge or split any slice?

Iterate until the operator approves. Do not proceed to stage 2 without approval.

Bounded context + CONTEXT-MAP (slice = context)

Each slice owns one bounded context — name it (glossary terms) in the slice's Bounded context: field. Format for CONTEXT-MAP.md = the single source domain-modeling — do NOT re-describe it here.

• Single context (one slice, or all slices share one context): stays laconic — one root CONTEXT.md, no CONTEXT-MAP.
• ≥2 contexts: finalize the root CONTEXT-MAP.md that intake seeded — bind each context to its slice <slug> and complete the Relationships section (upstream/downstream, shared types → internal/shared/). Intake identified the contexts; you bind them to slugs.
• Ordering: docs/design/slice-<slug>/ does not exist yet (built by program-design). You finalize the map; the per-context CONTEXT.md co-locates into the design package when it is built (co-location B — knowledge in docs/design/, never internal/).

Slice template (one per slice in slices.md)

## Slice <NN>: <title in glossary terms>

Status: `todo`
External input: <one endpoint or one consumed message>
Owns package: `internal/<slug>/`   ← MANDATORY, always (incl. single-slice); the slice's
                                      code lives here. Layer-keyed roots (internal/httpapi,
                                      internal/io, …) are forbidden — `program-design` fills
                                      this root, `validate-layout` gates it.
Bounded context: <context name in glossary terms>   ← slice = one bounded context
Use case(s) covered: <ref to Cockburn use case section>

### What to build
End-to-end behavior of this slice (not layer-by-layer). What goes in, what comes out,
which failure modes are visible to the consumer.

### Acceptance criteria
- [ ] <criterion 1>
- [ ] <criterion 2>

### Blocked by
<slice numbers, or "None — can start immediately">

Granularity router

Symptom	Verdict	Action
Slice touches 2+ external inputs	too coarse	split — one input per slice
Slice is "add a field / a layer" with no end-to-end path	too fine / horizontal	merge into its end-to-end slice
Slice cannot be demoed without another unfinished slice	dependency, not a split	record under Blocked by
Two slices always change together	over-split	merge

STOP

• FRD or high-level plan missing → STOP, run requirements-intake first.
• A slice maps to more than one external input → STOP, split (breaks the 1-slice-1-Request invariant).
• Operator has not approved the backlog → STOP, do not hand off to stage 2.

Definition of Done

• .agent/planner/slices.md exists, one section per slice, dependency-ordered.
• Every slice: exactly one external input, acceptance criteria, Blocked by, use-case reference.
• Operator approved the granularity and dependencies.