vertical-slice-planning

Vertical Slice Planning

Overview

Bridge the gap between an approved design and implementation plans. Decompose a design spec into vertical slices, track them as a master + sub-issues in Linear, then invoke /writing-plans for each slice. Every slice must be independently testable and deliverable end-to-end.

Core principle: A vertical slice cuts through all layers (schema, service, API, UI) to deliver one thin, working feature. A horizontal slice delivers one layer across all features — that is wrong.

When to Use

• Design spec is approved and ready for implementation
• Feature spans multiple subsystems or phases
• Work needs Linear tracking before plans are written

When NOT to use:

• Feature is small enough for a single plan (one /writing-plans invocation covers it)
• No design spec exists yet (use brainstorming first)

Process

digraph vertical_slice_planning {
    "Read approved design spec" [shape=box];
    "Identify vertical slices" [shape=box];
    "Evaluate: each slice end-to-end?" [shape=diamond];
    "Re-slice until vertical" [shape=box];
    "Create master Linear issue" [shape=box];
    "Create sub-issue per slice" [shape=box];
    "Set dependency graph on sub-issues" [shape=box];
    "For each slice: invoke /writing-plans" [shape=box];
    "All plans written?" [shape=diamond];
    "Notify user: all plans ready" [shape=doublecircle];

    "Read approved design spec" -> "Identify vertical slices";
    "Identify vertical slices" -> "Evaluate: each slice end-to-end?";
    "Evaluate: each slice end-to-end?" -> "Re-slice until vertical" [label="no — horizontal layers detected"];
    "Re-slice until vertical" -> "Evaluate: each slice end-to-end?";
    "Evaluate: each slice end-to-end?" -> "Create master Linear issue" [label="yes"];
    "Create master Linear issue" -> "Create sub-issue per slice";
    "Create sub-issue per slice" -> "Set dependency graph on sub-issues";
    "Set dependency graph on sub-issues" -> "For each slice: invoke /writing-plans";
    "For each slice: invoke /writing-plans" -> "All plans written?";
    "All plans written?" -> "For each slice: invoke /writing-plans" [label="no — next slice"];
    "All plans written?" -> "Notify user: all plans ready" [label="yes"];
}

Step 1: Read the Design Spec

Read the full approved design. Understand all components, data flows, and dependencies. Note the spec path — you will reference it in Linear issues.

Step 2: Identify Vertical Slices

Do NOT map spec sections 1:1 as slices. Spec sections are often organized by concept (schema, then logic, then API, then UI) — that is horizontal decomposition.

Instead, list every candidate slice and explicitly apply the vertical slice test to each one. Write out the evaluation — don't skip it because "it's obvious." The evaluation is the deliverable of this step.

For each candidate, ask: "Can a user (or agent, or test) exercise this slice end-to-end without any other slice being implemented?"

Vertical slice test — all three must be true:

1. The slice touches every layer it needs (schema + service + API + test) to be independently deployable
2. A developer can demo or test the slice in isolation after merging
3. Removing this slice from the plan does not break any other slice

Horizontal slice red flags:

• "All database work" / "All API endpoints" / "All UI components" as a single slice
• A slice that produces artifacts no other code can exercise yet
• A slice described as "infrastructure" or "foundation" with no user-facing behavior

When the spec has pre-defined phases: Evaluate whether each phase passes the vertical slice test. Phases that are purely additive DDL with no exercisable behavior are horizontal — combine them with the first slice that uses them, or add a minimal smoke test path.

Step 3: Create Master Linear Issue

Create one master issue that describes the full feature. Include:

• Link to the design spec
• Summary of all slices (numbered list)
• Dependency graph between slices (text or ASCII)

Use the Linear MCP save_issue tool. The master issue title should match the feature name from the design spec.

Step 4: Create Sub-Issues

For each vertical slice, create a sub-issue under the master issue using parentId. Each sub-issue should have:

• A clear title: Slice N: [what this slice delivers]
• Description: scope summary, key files, acceptance criteria
• Dependencies set via blockedBy where slices depend on each other

Dependency rules:

• Only set real dependencies — slices that literally cannot start until another merges
• Parallel-safe slices should have no dependency between them
• The dependency graph should be a DAG, not a chain (chains mean you sliced horizontally)

Step 5: Write Plans per Slice

For each slice, invoke /writing-plans (the superpowers:writing-plans skill). Pass the slice scope, not the full design spec — the plan should be focused on that slice only.

Each plan is saved to docs/superpowers/plans/ following the writing-plans convention.

After each plan is written, update the corresponding Linear sub-issue with a link to the plan file. Use save_issue with the sub-issue id and add the plan path via links.

Do all plans in sequence. Do not skip slices or defer "later" plans. The user asked for all plans — deliver all plans.

Step 6: Notify User

When all plans are written, report:

• Total number of slices and plans created
• The master Linear issue identifier
• Which slices can run in parallel vs which are sequential
• Suggest execution approach (subagent-driven-development or executing-plans)

Common Mistakes

Rationalizations You Will Hear (Including From Yourself)

Red Flags — STOP and Re-Evaluate

• You are about to create a plan without a master Linear issue existing
• A slice has no testable behavior on its own
• All your slices must execute in strict sequence (1 → 2 → 3 → 4 → 5)
• You skipped the vertical slice test because "the spec already breaks it down"
• You are deferring Linear issues because the user said to move fast
• A slice is called "Schema" or "Infrastructure" or "Foundation" with no end-to-end path

All of these mean: STOP. Go back to Step 2 and re-slice.