kb-plan

KB Plan - Vertical Slice Decomposition

<!-- Inspired by mattpocock/skills to-issues - credit: github.com/mattpocock/skills -->

Break work into independently executable vertical slices (tracer bullets). Each slice cuts through all relevant layers end-to-end. Avoid horizontal phases.

Quick Start

1. Read the brainstorm, PRD, or feature description.
2. Draft thin end-to-end slices with dependencies and verification modes.
3. Review the breakdown yourself against the source material; ask the user only for blocking decisions.
4. Write one KB manifest plus one plan file per slice.
5. Create or update the manifest gate_ledger; plan-to-work must be passed before kb-work may execute.
6. After writing the manifest, continue to kb-work <manifest-path> only when execution was requested or an orchestrator called this plan. Otherwise ask once and print the exact next command.
7. Stage or commit only the generated files when the user explicitly asked for a commit.

Interaction Method

kb-gate owns blocking-question policy. Record safe, reversible assumptions; route unresolved ask-now, research-first, or material scope/architecture/ safety/verification decisions back through that gate.

Always produce the manifest and slice plans first. Continue directly to kb-work <manifest-path> when the user requested execution or an orchestrator called planning. Otherwise ask once whether to continue; if not, print the exact next command.

Input

<input> #$ARGUMENTS </input>

If input is empty: Check todo.md and docs/brainstorms/ for the active or most recent brainstorm. If exactly one likely source exists, use it and record the assumption. If multiple plausible sources exist, ask which one to use. If none exist, ask: "What feature or work should I slice?"

If input is a brainstorm path: Read it thoroughly. This is the source of truth for what to build. Carry forward all decisions, scope boundaries, and requirements.

If input is a handoff path: Do source discovery before planning:

1. Read the handoff.
2. Check the handoff for explicit Brainstorm:, Requirements:, Source:, Manifest:, or Plan: pointers.
3. Check todo.md for a source pointer tied to that handoff or feature.
4. Look for matching existing source artifacts under project-root paths only:
   • docs/brainstorms/*<topic>*
   • docs/requirements/*<topic>* if that folder exists
   • docs/plans/*<topic>*
5. If a matching brainstorm or requirements doc exists, read it and use it as the planning source of truth. The handoff becomes restart context, not the primary source.
6. If a matching manifest already exists, ask whether to resume with kb-work instead of creating a duplicate plan.
7. If no source exists and the handoff is concrete enough, plan from the handoff and record source: handoff.
8. If no source exists and the handoff leaves material product or architecture decisions open, stop and route to kb-brainstorm.

If input is a feature description: Proceed directly to decomposition.

Core Rules

Vertical Slices Only

Each slice must deliver a narrow but complete path through every relevant layer: schema, service, API, UI, tests, docs, or ops as applicable. A completed slice is demoable or verifiable on its own.

WRONG (horizontal phases):
  Task 1: Create database schema
  Task 2: Build service layer
  Task 3: Add API routes
  Task 4: Build frontend

RIGHT (vertical slices):
  Task 1: Award points on lesson completion + show on dashboard
  Task 2: Track streaks (builds on task 1)
  Task 3: Add level progression display

Enabling Slices Are Acceptable

Some work is legitimately enabling infrastructure: migrations, auth plumbing, shared config, repo setup. Allow enabling slices only when:

• They unlock a named downstream slice
• They are the smallest viable prerequisite
• The slice names its immediate consumer(s)

Live-Steering Slices

For recurring, scheduled, or trend-improvement work routed from kb-goal, include the control-loop fields in the manifest or the first slice plan:

• set point: the invariant, threshold, or direction being driven;
• sensor: the command, query, test, or review signal that measures the gap;
• controller: how the next small reviewable increment is selected;
• actuator: the KB lane, coding agent, or workflow that applies the change;
• disturbances: outside changes the loop must tolerate;
• dampener: optional regression gate that keeps the measured problem from getting worse while the loop improves it;
• scope gate, batch size, WIP bound, and steering-memory path.

Do not force this framing onto one-shot feature work. Do not invent separate sensor, controller, and actuator artifacts when the repo's real toolchain fuses them; record the fused component and the selection policy. HumanLayer-style CI, Bun, CodeLayer, or GitHub Actions runners are examples, not KB defaults.

Every Slice Has a Verification Strategy

Mode	When	Gate
tdd	Behavior changes, business logic	Define protected oracle first when practical -> prove RED -> implement -> unchanged oracle passes
integration	Wiring, cross-boundary, API contracts	Integration test proves path works
functional	User-visible workflow, UI/API/CLI journey, escaped bug	Workflow-level check proves the user path
verification-only	Config, scaffolding, ops	Builds pass, no regression
hitl	UX taste, design judgment	Human confirms acceptable

Also record test_level and functional_risk for each slice. kb-functional-test owns this classification:

• test_level: none, unit, integration, functional-api, functional-cli, functional-browser, functional-native-gui, or full
• functional_risk: none, narrow, broad, or full
• execution_class: cli, headless-browser, visible-browser, or native-gui

visible-browser and native-gui are classification-only in the portable proof runner: automatic execution is blocked before process launch. If an attended GUI session is genuinely required, record the blocker and leave that explicit user/host action outside proof-run; do not add an approval artifact to the manifest.

Use unit only when a unit test can genuinely prove the changed behavior. Use functional levels when a unit test could pass while the user-visible, API, CLI, browser, persistence, auth/session, streaming, or integration path is broken.

Process

1. Understand the Source Material

Read the brainstorm/PRD/description. Extract:

• What behaviors need to exist
• What the user-visible outcomes are
• What constraints/dependencies exist
• What's explicitly out of scope
• Question Gate state: unresolved ask-now/research-first blockers, safe assumptions, deferred planning questions, and parked forbidden claims.

Planning cannot launder brainstorm ambiguity.

If the source has unresolved ask-now or research-first items, stop before decomposition. Write or update the brainstorm-to-plan gate as blocked or needs-human and set allowed_next_action to the smallest repair action, such as kb-brainstorm <requirements-path>.

1.5. Research (Parallel)

Use the kb-map context already loaded. When material uncertainty remains— especially security, payments, external APIs, privacy, or unfamiliar framework behavior—invoke kb-research and point affected slices to its evidence. Carry relevant active landmines into constraints and verification.

2. Draft Vertical Slices

Break the work into thin end-to-end slices. For each slice, determine:

• Title - short descriptive name
• What it delivers - end-to-end behavior description
• Verification mode - tdd / integration / verification-only / hitl. For tdd, record the oracle path/command before implementation whenever practical.
• Test level - none / unit / integration / functional-api / functional-cli / functional-browser / functional-native-gui / full
• Functional risk - none / narrow / broad / full
• Model tier - the small / medium / large correction and authority tier required if the first implementation attempt fails; Planner is a separate orchestration role
• Model tier reason - one falsifiable explanation tied to uncertainty, blast radius, coupling, reversibility, authority, or verification burden
• Model requirements - capabilities, tools, context, risk, and proof shape the work-time selector must consider
• Escalation triggers - observable conditions that require a higher tier
• Workspace isolation intent - one plan-run worktree per mutating manifest group, shared-serial slices, conflict domains, and shared resources. Plans record intent only, never live paths, branch names, session IDs, cleanup state, or owner tokens.
• Blocked by - which other slices must complete first, or none
• HITL flag - does this need human judgment? Most should be false if the brainstorm was thorough.
• Expected files - best current forecast of files this slice may create or modify, with operation type. Used by kb-work as an orientation and review-scope seed, not as a literal allowlist.
• Impact forecast - when kb-map provided an impact packet, carry forward impacted files/symbols, tests, docs, freshness, fallback, and limitations. Stale or missing graph evidence must become an explicit file-native fallback, not a silent confidence claim.
• Context packet - for non-trivial slices, the bounded execution payload: memory/source files already checked, deterministic prefetch, constraints, acceptance/proof targets, minimum execution tier, allowed tools/search policy, and escalation triggers. Tiny doc-only or mechanical slices may omit it with a one-line reason.

Each entry in expected_files should specify:

• path — the file path
• op — create, edit, or delete
• scope — one-line description of what specifically changes (for edit op

---

Content truncated.