All Skills
/to-plan Phase 2: Devising a Plan

The /to-plan Skill

Transforms approved specifications into vertical tracer bullets, orders Clean Architecture seams bottom-up, plans Contingency Plan B, and enforces The Pause Rule.

"Second. Find the connection between the data and the unknown. You may be obliged to consider auxiliary problems if an immediate connection cannot be found. You should obtain eventually a plan of the solution." — George Pólya, How to Solve It (1945)
TERMINAL OR CHAT PROMPT 
/to-plan @docs/spec/checkout-spec.md Formulate tactical vertical tracer bullets, bottom-up dependencies, and contingency Plan B.

What it does

to-plan takes an approved Technical Specification (docs/spec/{slug}-spec.md) and decomposes it into an execution sequence of vertical "tracer bullets". Instead of grouping chores by technical layer (e.g. building all DB tables in Phase 1, then APIs in Phase 2), it cuts end-to-end through Domain Entities, Use Cases, Adapters, and UI in thin, independently demoable slices.

It maps dependencies bottom-up using Pappus analysis, bounds all tasks between Size XS and M (strictly prohibiting bloated XL tasks), binds every ticket to speed-tiered verification commands (check:task, check:full), plans fallback strategies (Contingency Plan B), and authors exactly one plan file at docs/plan/{slug}-plan.md. Upon writing the plan, it halts execution and enforces The Pause Rule.

When to reach for it

Where the work currently lives decides whether this is the right skill:

The work is… Reach for
An approved Technical Specification ready for tactical decomposition /to-plan @docs/spec/{slug}-spec.md
A wide refactor with broad blast radius needing Expand-Migrate-Contract /to-plan
An approved plan ready for code execution /to-code @docs/plan/{slug}-plan.md
Requirements or schemas not yet specified /to-spec first
A routine mechanical change (≤ 2 files) /to-quick-fix
A plan requiring assumption interrogation and stress-testing /to-clarify @docs/plan/{slug}-plan.md

Prerequisites

  • Approved Technical Specification: Requires an existing specification file at docs/spec/{slug}-spec.md with typed contracts and acceptance criteria.
  • Mechanical Commands Grounding: Verification commands (check:task, check:full) must be documented in docs/ARCHITECTURE.md Section 8.
  • Strict Plan-Only Rule: Writing application source code in /src or /lib is strictly prohibited during this phase.

What one run does

A single planning run follows seven tactical steps:

  1. Context Ingestion & Pre-Planning Analysis: Ingests the upstream Spec. Scans for prefactoring opportunities ("Make the change easy, then make the easy change") to prepare seams before feature additions.
  2. Working Backwards & Dependency Topography: Works backwards from user value to data inputs (Pappus analysis). Maps hierarchy bottom-up: Entities → Ports → Use Cases → Adapters → UI.
  3. Vertical Feature Slicing (Tracer Bullets): Slices features vertically through all layers. Layer-by-layer horizontal slicing is strictly forbidden. Applies Expand-Migrate-Contract for wide refactors.
  4. Task Sizing Enforcement: Caps tasks to Size XS (1 file), S (1–2 files), or M (3–5 files). Prohibits and decomposes bloated XL tasks (≥ 8 files).
  5. Phased Delivery & Contingency Plan B: Sequences work into 4 phases: Land (Minimal Viable Tracer Bullet) → Core Experience → Expand → Polish. Formulates Plan B fallbacks with explicit pivot triggers.
  6. Single Plan File Authoring: Writes strictly one canonical plan file to docs/plan/{slug}-plan.md, binding every task 1:1 to Ref ID (REQ-XXX) and AC Ref (AC-XXX).
  7. 🛑 The Pause Rule Enforcement: Halts execution immediately upon file generation. Demands explicit user confirmation before any code is written in /to-code.

Common questions

Why did the agent stop after generating the plan instead of writing code?

The Pause Rule! Phase 2 ends strictly at plan generation. George Pólya's core philosophy mandates that execution must never proceed until the human reviewer verifies that the plan's connection between data and unknown is sound.

Why does /to-plan forbid horizontal slicing (layer-by-layer)?

Building layer-by-layer (e.g. all database tables first, all APIs second, all UI third) produces untested intermediate silos that cannot be demoed or verified end-to-end. Vertical tracer bullets deliver runnable, testable value at every step.

What is Contingency Plan B?

Pólya's heuristic: "Have two strings to your bow." Every high-risk external dependency or complex migration must have a pre-planned fallback strategy with concrete triggers, preventing the project from getting trapped in blind alleys.

It's working if

  • Exactly one implementation plan is written to docs/plan/{slug}-plan.md (zero shadow copies).
  • All tasks are vertically sliced and sized XS, S, or M (zero XL tasks).
  • Every functional task maps 1:1 to an upstream Ref ID (REQ-XXX) and AC Ref (AC-XXX).
  • Each task binds to speed-tiered verification commands (check:task, check:full).
  • The agent halts immediately upon plan generation and asks for your confirmation before writing code.

Where it fits

to-plan is Phase 2 in the main idea-to-ship pipeline: 

/to-explore → /to-prd → /to-spec → /to-clarify → 📋 /to-plan → 🛑 PAUSE → /to-code → /to-review → /to-docs

It receives an approved specification from /to-spec or cleared audit from /to-clarify. Once the plan is confirmed at The Pause Rule, it hands off to /to-code for tracer-bullet implementation.