better-plan

Parse the user's input:

• First argument is the task name (matches the docs directory, e.g., offline-sync)

Phase 1 — Read inputs

Read these files from docs/{task-name}/:

• structure.md — required (the technical blueprint)
• design.md — required (alignment decisions)

If structure.md or design.md is missing, tell the user which is missing and stop: "Cannot generate a plan without {missing file}. Run /{missing skill} {task-name} first."

Phase 2 — Generate the plan

The plan is derived mechanically from structure.md. The structure doc's Change Ordering and Testing Strategy are the primary inputs. Design decisions and technical decisions provide the rationale and constraints.

Slice the work into vertical phases. Each phase delivers a complete, working slice from bottom to top — data layer through UI (or whatever the vertical looks like for this task). Never organize horizontally (all models first, then all repos, etc.).

A phase may contain multiple steps if they form one logical vertical slice. A step is a single atomic unit of work — one file or a tightly coupled set of files.

Write docs/{task-name}/plan.md with this structure:

# Plan: {Task Name}

> Generated from: [design.md](design.md), [structure.md](structure.md)
>
> Execution: work through phases top to bottom. Each phase ends with a
> checkpoint. Do not proceed to the next phase until the checkpoint passes.

---

## Phase 1: {Vertical Slice Name}

*{One sentence: what this phase delivers end-to-end.}*

### Steps

#### 1.1 — {Step name}

**Do:**
{Precise instructions. What file(s) to create or modify, what types/signatures to use, what logic to implement. Reference structure.md's Data & Types and Interfaces & Contracts sections directly — use the actual signatures defined there.}

**Why:**
{One line connecting this to a design decision or structural requirement.}

#### 1.2 — {Step name}

**Do:**
...

**Why:**
...

### Checkpoint

{Concrete verification. Exactly what to run, what to check, what the expected outcome is.}

- [ ] **Build:** `{build command or "project compiles"}`
- [ ] **Test:** `{test command, manual verification step, or specific assertion}`
  - Expected: {what success looks like}
- [ ] **Verify:** {any additional check — e.g., "query X returns Y", "screen shows Z"}

**If checkpoint fails:** {What to investigate. Common failure modes for this type of change.}

### Manual Verification *(optional — include only if this phase's output needs human eyes-on, e.g. UI on a device, staging server behavior, end-to-end flow not covered by automated tests)*

- [ ] **Step 1:** {concrete action to perform} → {expected observation}
- [ ] **Step 2:** {next action} → {expected observation}

---

## Phase 2: {Vertical Slice Name}

...

---

## Phase N: {Final Slice}

...

### Final Checkpoint

{End-to-end verification that the complete feature works as described in design.md's End State.}

- [ ] ...

Rules for phase construction

1. Vertical, not horizontal. Each phase must touch the full stack relevant to its slice. "Add the domain model, repository, and screen for feature X" is one phase. "Add all domain models" is not.
2. Each phase compiles. After completing a phase, the project must build. If a phase introduces an interface, it must also provide at least a stub implementation in the same phase.
3. Steps within a phase are sequential. Step 1.2 may depend on 1.1. But phases themselves should be as independent as possible.
4. Checkpoints are concrete. No "verify it works." Instead: the specific build command, test command, or manual step. Include expected output where possible.
5. Instructions reference structure.md directly. When a step says "create ThingRepository," the plan should include the exact signature from structure.md's Interfaces & Contracts section. The implementer (you, in a future conversation) should not need to re-derive anything.
6. Include the types and signatures inline. Copy the relevant Python signatures/type hints from structure.md into the step's Do section. The plan must be self-contained — readable without flipping back to structure.md during execution.
7. Keep phases small. Prefer more phases with fewer steps over fewer phases with many steps. A phase with 6+ steps is probably two phases.
8. First phase is foundation. If there are shared types, base interfaces, or infrastructure needed by multiple slices, the first phase sets that up — but still as a vertical slice (e.g., one entity end-to-end that establishes the pattern).
9. Last phase is integration. If phases were somewhat independent vertical slices, the final phase wires them together and runs end-to-end verification.
10. Manual verification only where needed. Include a ### Manual Verification section only when the phase's output requires human eyes-on — a UI on a real device, a staging deployment's visible behavior, an end-to-end flow across services not covered by automated tests. Do not include it for internal changes (pure functions, data-loading plumbing, internal modules) that the automated checkpoint fully covers. When included, list concrete steps with one action and one expected observation per line. The /execute skill presents these to the user one at a time at the end of the phase — so keep each step atomic and observable.

11. No vacuous test filters. A pytest -k Foo filter (or pytest tests/test_foo.py) that matches zero tests is not a checkpoint — it's a planning gap that fakes coverage. Before writing a test command into a checkpoint, you must ensure either (a) the test class/file already exists in the repo, or (b) the same phase contains an explicit step that creates it. Annotations like (vacuous — no pre-existing tests) are forbidden — they document the gap instead of fixing it. Resolution paths:

    • Gap fixable in this phase. Add a step (e.g., 2.0 — Add test_hve_gate.py covering existing branches) before the change-introducing steps so the new behavior lands on top of an existing safety net. Then the checkpoint's test filter has something to match.
    • No tests yet, but a sibling integration test covers the surface. Replace the unit-test filter with the integration-test filter that actually exists, and call out in the phase's intro paragraph what is and isn't covered.
    • Convention says a unit test should exist but writing it is out of scope. Don't paper over it — split the test-authoring into its own preceding phase, or note the missing-test risk in the phase's **If checkpoint fails:** block as a known coverage gap that /execute will surface.

    Before finalizing the plan, run find / grep to verify every test class named in a --tests filter actually exists. If it doesn't, do (a), (b), or (c) — not parentheses.

Deriving phases from structure.md

Map structure.md's sections to the plan:

• Change Ordering → phase sequence and step grouping
• Code Shape (New/Modified) → step Do instructions
• Data & Types → inline type definitions in steps
• Interfaces & Contracts → inline signatures in steps
• Testing Strategy → checkpoint test commands
• Libraries & Dependencies → called out in the first step that needs them
• Algorithms & Logic → detailed in the step that implements them

Phase 3 — Output

Write the plan to docs/{task-name}/plan.md.

Tell the user:

• The plan is at docs/{task-name}/plan.md
• Number of phases
• Brief one-line description of each phase
• "Say 'do phase 1' to begin execution."

Do not ask questions or start a conversation. The design and structure docs already resolved the unknowns. If something in structure.md is ambiguous enough that you cannot write a concrete step, note it as a warning at the top of the plan rather than blocking generation.