planning

Planning in Vertical Slices

Plan by vertical slices wherever possible. Each slice delivers the smallest end-to-end behavior a real actor can observe, while leaving the codebase in a known-good state where all tests pass.

Horizontal work is allowed only when it explicitly unblocks the next vertical slice and is independently verifiable, or when it belongs to an explicitly selected reduction program whose terminal state retires one complete mechanism while conserving behavior.

In Claude Code environments where they exist, use /plan to create plans and /continue after a merged independent PR or to advance and sync an active stack. Otherwise, create or update the plan artifact directly and resume through the active harness or repository workflow.

Relationship To Story Splitting

story-splitting decides what small user-value stories exist. planning decides how to implement selected stories safely.

Use story-splitting before this skill when the request is still an epic, large story, feature idea, roadmap item, or backlog item with multiple possible customer outcomes. Once a child story or narrow capability has been selected, use this skill to create or update the repository's planning artifact with implementation slices, acceptance criteria, evidence routes, and a delivery shape for each slice.

Keep three units distinct:

A sequence is work order; a stack is branch topology. Default each slice to a trunk-based PR. Keep slice PRs independent when they can merge in any order without blocking or duplicating work, or when the next branch starts only after its predecessor lands. Load stack-pull-requests when one slice needs review layers or when later slices should start on the same evolving baseline before earlier PRs merge. Hard dependency is sufficient but not required; deliberate flow lineage may justify a stack. Speculative backtracking alone does not.

If a plan starts producing database-only, API-only, UI-only, or "do all plumbing first" slices, pause and return to story-splitting unless the horizontal work explicitly unlocks the next vertical slice with independent verification or advances an explicitly selected reduction program toward its named terminal mechanism-removal state.

Use grill-me where installed before planning when the selected story still contains unresolved product or design decisions. Otherwise, ask one focused question at a time, with a recommended answer and its trade-off. Use find-gaps before or after drafting the plan when acceptance criteria, failure modes, roles, states, or release constraints are missing or unverifiable.

Before freezing slices that introduce a material generic mechanism or durable new dependency, run the proportionate evaluate-existing-solutions preflight, due diligence, or full comparison. Link a decision-owner-accepted result when a choice was unresolved. Planning sequences the chosen solution; it does not silently turn the first plausible library or a bespoke sketch into the plan.

Plans Directory

Use the repository-declared planning workflow and location. A repository may own plans in documentation, issues, or another named system. When no owner is declared and a file-backed plan is appropriate, use plans/ at the project root with a descriptive filename (for example, plans/gift-tracking.md).

Discover active plans through that workflow. For the fallback layout, use ls plans/.

Multiple plans can coexist — each is independent and won't conflict across branches or worktrees because they have unique filenames.

When a plan is complete: follow the repository's lifecycle rule. For the fallback layout, delete the plan file and remove plans/ when empty.

Prefer Small Reviewable PRs

Default to the smallest known-good vertical units, with one trunk-based PR per slice. Use a cross-slice stack when upper slices have hard dependency or deliberate flow lineage, will be in flight before lower merge, and review, lead-time, or correction-routing benefits earn the cascade cost. Use an intra-slice stack when one fixed slice still needs focused dependent review layers.

Why this matters: Small PRs are easier to review, easier to revert, and easier to reason about. When something breaks, the cause is obvious. When a PR sits in review, it doesn't block unrelated work. The goal is to stay as close to main as possible at all times.

A PR is too big when the reviewer needs to hold multiple unrelated concepts in their head to understand it, or when you'd struggle to write a clear 1-3 sentence summary of what it does.

There will be exceptions. Use judgement: first define honest vertical slices, then decide whether they stay independent, share a cross-slice hard/flow stack, or one slice needs intra-slice review layers.

What Makes a Vertical Slice

A vertical slice is not "small because it touches one layer." It is small because it delivers one observable behavior through the real production path.

Each slice MUST name:

• Actor: who receives the value (user, admin, API client, scheduled job, support operator)
• Trigger: what starts the behavior (click, request, event, command, timer)
• Observable outcome: what proves the behavior happened
• Production path: the real surfaces, use case, domain logic, persistence, and external adapters involved
• Smallest deployable value: the narrowest useful version that can ship safely

Good slices are often thin but complete:

• A form submits one valid field through the real API and persists it
• A background job handles one event type and emits the expected audit result
• A CLI command supports one input shape and returns stable stdout/stderr
• A read-only screen shows one real state using production data loading

Choosing Slices

Before writing plan slices:

1. Name the outcome — describe the user- or system-visible result in one sentence.
2. Map the path — list the real entry point, business path, state change, output, and observability.
3. Pick the walking skeleton — choose the thinnest end-to-end version that proves the path works.
4. Add one behavior or state at a time — validation, permissions, error states, empty states, retries, analytics, and polish become later slices.
5. Check reversibility — each slice should be easy to revert or disable without undoing unrelated work.

Ask "what is the smallest real behavior we can ship?" before asking "what files need to change?" If the answer still contains multiple customer outcomes, roles, workflow branches, or quality levels, load story-splitting and split the parent before writing the plan.

Horizontal Work Exceptions

Avoid plans that do all database, API, UI, or infrastructure work up front. Horizontal work may be its own slice only when all applicable conditions are true:

• It names the next vertical slice it unlocks, or belongs to an explicitly selected reduction program with a terminal mechanism-removal outcome
• It leaves the codebase deployable
• It has observable verification (test, command output, migration dry-run, or runtime check)
• It is smaller than doing it inside the vertical slice
• It does not introduce unused abstractions or speculative flexibility

Valid horizontal exceptions include dependency upgrades, migrations, test harness setup, infrastructure wiring, mechanical refactors, safety fixes, and a selected reduce-system-complexity program whose terminal state conserves behavior while retiring one complete mechanism. Keep them rare and explicit. An intermediate reduction transition may temporarily add a bridge when it is independently verifiable and the same plan names the terminal slice and behavior/mechanism gates; record an owner, removal condition, and bounded lifetime for any bridge, or N/A when none exists.

What Makes a Known-Good Slice

Each slice MUST:

• Leave all tests passing
• Be independently deployable
• Have clear done criteria
• Fit in a single PR by default, or have an approved stack-pull-requests delivery map
• Be describable in one sentence
• Deliver or directly unblock observable behavior, or safely advance an explicitly selected reduction program toward its terminal behavior/mechanism gates

A slice is the unit of planning and known-good value. By default it is also one review PR against trunk. In a cross-slice stack, each PR may own a complete slice and that slice completes when its PR lands bottom-up. In an intra-slice stack, dependent PR layers are focused review boundaries and the slice completes when its top lands. Within each behavior-changing PR boundary, fast RED-GREEN-REFACTOR increments may produce multiple commits; mutation testing or alternate evidence runs once when that boundary is otherwise PR-ready, not after each increment.

Content truncated.