fix: review the saved plan before execution

Present the saved, self-reviewed plan for human review before implementation. Request an execution method when none was supplied; preserve an existing choice and ask only for plan review when the human already chose a method. This completes the shared-intent repair without interpreting approval of an earlier idea or scope as approval of an unseen implementation plan. Four saved-plan smoke cases covered old/new wording with/without a prior choice; all passed the narrower handoff checks, including old controls, so this is not evidence of measured improvement. Jesse requested consolidation into two commits and removal of the supporting spec/plan research content from the PR. The skill bytes remain identical to the reviewed branch; the complete research and original history are retained in local archives.
fix: establish shared intent before implementation
2026-09-05 13:15:37 +00:00 · 2026-09-04 16:03:59 -07:00 · 2026-09-04 16:03:59 -07:00
5 changed files with 64 additions and 228 deletions
@@ -11,12 +11,48 @@ Start by classifying how much process the request needs, then work
 through your path: understand the context, refine the idea, present a
 design, and get your human partner's approval.
 ## Establish Shared Understanding
 The outcome of brainstorming is an understanding your human partner can
 recognize and correct, grounded in what they want to accomplish.
 1. **Discover intent.** Use the request and available context to identify
   the intended outcome, who it is for, and what success looks like. When
   that information is missing, ask one focused question about purpose or
   intended use before proposing features or an approach. Knowing the app
   genre does not tell you why your partner wants it. Gathering missing
   requirements does not ask them to authorize the task again.
 2. **Write back your understanding.** Summarize the intended outcome,
   relevant constraints, and success criteria in a short note your partner
   can assess. Separate what they said from assumptions. Invite correction
   and incorporate their answer before treating this as the design brief.
 3. **Carry intent into the design.** Preserve the agreed understanding in
   the selected path's design artifact: the written spec for architectural
   work, or the in-chat design/probe for bounded work and spikes. Check
   proposed features and technical choices against that understanding.
 When the request already supplies the purpose and constraints, reflect
 that understanding instead of asking the same questions again. Keep the
 note concise; its accuracy and the opportunity to correct it matter.
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any
+Before taking any implementation action, including invoking an
-project, or take any implementation action until you have told your
+implementation skill, writing product code, scaffolding, installing
-human partner what you intend and they have approved it. This applies
+product dependencies, or creating an external project, complete the
-to EVERY task on EVERY path below — the ceremony scales with the task;
+selected path's prerequisites:
-the approval gate never does.
+
 - Spike: the human partner approves the question and probe.
 - Bounded: the human partner approves the short in-chat design.
 - Architectural: the human partner reviews and approves the written spec,
  then reviews the written implementation plan and selects its execution
  method. Conversational design approval only permits writing the spec;
  written-spec approval only permits invoking writing-plans.
 A reply approves the stage actually presented. Approval of an idea or
 feature scope does not approve artifacts that do not exist yet. Resume
 at the earliest incomplete stage; do not turn one approval into permission
 to skip the rest of the selected path. Read-only project exploration is
 allowed while those prerequisites remain incomplete.
 </HARD-GATE>
 ## Three Paths
@@ -53,18 +89,17 @@ stop, say so, and step up. Nothing downgrades mid-task.
 ## Anti-Pattern: "Too Simple To Need Approval"
-Every path ends with your human partner approving your intent before
+Every path ends with your human partner approving the required design
-implementation. A todo list, a single-function utility, a config
+before implementation. A bounded change may need only two sentences in
-change — the design may be two sentences in chat, but you MUST present
+chat. A new todo-list project is architectural and requires the written
-it and get approval. "Simple" tasks are where unexamined assumptions
+spec and planning handoffs. Scale the artifact to the selected path;
-cause the most wasted work. What scales with simplicity is the
+complete that path's reviews before implementation.
 artifact, never the approval.
 ## Red Flags
 | Thought | Reality |
 |---------|---------|
-| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
+| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. |
 | "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
 | "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
 | "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
@@ -173,14 +173,6 @@ its own text agrees with itself — the tests it specifies against the code it
 specifies, the files it creates against the files it later touches. "The scan
 is clean" without those rows is not a scan you ran.
 **When the plan's header declares `Plan shape: skeleton-first`,** the
 table gets a final section: the DISPATCH PLAN — group the pending tasks
 into waves. Tasks in the same wave are mutually file-disjoint and consume
 no interface still under construction — dispatch each wave's implementers
 concurrently, one worktree per task, and integrate before the next wave;
 tasks that fail those conditions serialize. On a skeleton-first plan, a
 scan without a dispatch plan is not a scan you ran.
 Write the table to the ledger. Rule on everything you find before execution
 begins — each finding against the plan text that mandates it — and record
 each ruling in the ledger. If the scan is clean, proceed without comment.
@@ -195,10 +187,6 @@ Use the least powerful model that can handle each role to conserve cost and incr
 **Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
 When a task carries a **Tier:** field, follow it — the planner already
 ruled: mechanical → the cheapest available model; judgment → a standard
 model. Do not re-litigate the tier at dispatch.
 **Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
 **Architecture and design tasks**: use the most capable available model.
@@ -220,10 +208,7 @@ most expensive — which silently defeats this section.
 **Turn count beats token price.** Wall-clock and context cost scale with how
 many turns a subagent takes, and the cheapest models routinely take 2-3× the
 turns on multi-step work — costing more overall. Use a mid-tier model as the
-floor for reviewers and for implementers working from task contracts or
+floor for reviewers and for implementers working from prose descriptions.
 prose descriptions — unless the task's Tier line says mechanical: the
 planner has already ruled the deliverable fully specified, so treat a
 mechanical-tier contract like spelled-out content.
 When the task's plan text contains the complete code to write, the
 implementation is transcription plus testing: use the cheapest tier for
 that implementer. Single-file mechanical fixes also take the cheapest tier.
@@ -274,13 +259,7 @@ and fix-round diffs need it.
  know; (4) your resolution of any ambiguity you noticed in the brief;
  (5) the report-file path and report contract. Exact values (numbers,
  magic strings, signatures, test cases) appear only in the brief. Never
-  make a subagent read the whole plan file. When the brief is a contract
+  make a subagent read the whole plan file.
  (goal, success criteria, interfaces) rather than written-out code, item
  (3) also carries the elaboration the contract leaves to dispatch time:
  the interfaces as actually built by completed tasks, environment facts
  and discoveries from earlier reports, and any amendment rulings. There
  the success criteria name the cases the tests must cover, and the
  implementer designs its own code and tests within the contract.
 - **Report file:** name the implementer's report file after the brief
  (brief `…/task-N-brief.md` → report `…/task-N-report.md`) and put it in
  the dispatch prompt. The implementer writes the full report there and
@@ -301,26 +280,6 @@ and fix-round diffs need it.
 - Record the implementer's agent identity from the dispatch result —
  fix-loop rounds 1-3 resume this agent.
 - Never dispatch multiple implementation subagents in parallel (conflicts).
  The one exception is a skeleton-first plan whose dispatch plan shows two
  or more pending tasks mutually file-disjoint with none consuming an
  interface still under construction. Dispatch those implementers
  concurrently, each in its own worktree:
  - Record the integration base commit in the ledger before the first
    concurrent dispatch.
  - Create one worktree per concurrent task off that base
    (`git worktree add <repo-root>/.worktrees/task-<N> -b task-<N>
    <base>`); each dispatch's `Work from:` is its own worktree, and its
    BASE is that worktree's HEAD.
  - Review each task's diff as usual when it reports. Integrate reviewed
    branches in plan order: merge each into the integration branch
    (`git merge --no-ff task-<N>`), and run that task's verification
    commands after each merge.
  - A merge conflict or post-merge verification failure is that task's
    fix-loop round 1: rebase the task branch onto the current
    integration head in its worktree, then resume its implementer
    there. Never resolve conflicts yourself.
  - Remove each worktree (`git worktree remove`) once its branch is
    integrated, and record the integrated range in the ledger as usual.
 Template: [implementer-prompt.md](implementer-prompt.md)
@@ -479,16 +438,6 @@ message as your other bookkeeping:
 - `Task <N>: complete (commits <base7>..<head7>, <K> parked)` after a
  tripped breaker
 **On a skeleton-first plan,** write one plan-check line with the
 completion line. Re-read the remaining tasks against what this task
 actually established — interfaces as built, environment facts,
 discoveries in the report — and append either `Plan holds` or
 `Amendment: Task <M>: <what changes and why>` to the ledger. An
 amendment is plan authority applied at the plan layer: from then on the
 amended text IS the plan's text, and it rides into every affected task's
 dispatch under item (3). Never dispatch a task whose brief a completed
 task's report has already invalidated.
 Then mark the todo complete and move on. Never move to the next task while
 the review has open Critical/Important issues that are neither fixed nor
 parked-with-ruling at the cap.
@@ -5,11 +5,8 @@ Use this template when dispatching an implementer subagent.
 ```
 Subagent (general-purpose):
  description: "Implement Task N: [task name]"
-  model: [MODEL — REQUIRED: when the brief carries a Tier line, set from it:
+  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
-         mechanical → the cheapest model the subagent tool offers; judgment →
+         model silently inherits the session's most expensive one]
         a standard mid-tier model. Otherwise choose per SKILL.md Model
         Selection. An omitted model silently inherits the session's most
         expensive one]
  prompt: |
    You are implementing Task N: [task name]
@@ -22,30 +22,6 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
 ## Two Plan Shapes
 Before mapping files, classify the plan's shape and say the
 classification out loud — "this composes three subsystems, so I'll plan
 it skeleton-first" — so your human partner can override it:
 - **Task-by-task (default)** — tasks build the feature a component at a
  time, each step carrying the actual content the engineer needs. Use it
  for changes to code that already exists, for a spec that touches one
  subsystem, and whenever the alternative's conditions do not clearly
  hold. The rest of this skill describes this shape.
 - **Skeleton-first (alternative)** — Task 1 is the thinnest end-to-end
  slice through every subsystem the spec composes; later tasks widen it
  one component at a time, each from a contract rather than written-out
  code. Use it when the spec composes more than one subsystem AND a
  running end-to-end slice early is worth a longer total build. Read
  [skeleton-first-plans.md](skeleton-first-plans.md) before writing one
  — it adds one line to the plan header and replaces this skill's task
  granularity, task template, and plan-failure list.
 When in doubt, plan task-by-task. Skeleton-first buys an earlier running
 system and pays for it in total wall clock; it is a trade, not an
 upgrade.
 ## File Structure
 Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
@@ -176,15 +152,25 @@ If you find issues, fix them inline. No need to re-review — just fix and move
 ## Execution Handoff
-After saving the plan, offer execution choice:
+After saving and self-reviewing the plan, link it for your human partner
 to read. If they have already explicitly supplied an execution method, ask
 them to review the plan and confirm it captures what they want; wait for that
 review before implementation, then use the preserved method. Otherwise, ask
 them to review the plan and choose an execution method before implementation.
-**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:**
+**When no execution method has already been supplied:**
 **"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options:**
 **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration
 **2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints
-**Which approach?"**
+**Does the plan capture what you want, and which approach should we use?"**
 **When an execution method has already been supplied:**
 **"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"**
 **If Subagent-Driven chosen:**
 - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
@@ -1,131 +0,0 @@
 # Skeleton-First Plans
 The alternative plan shape from writing-plans' Two Plan Shapes router.
 Each section below replaces the same-named section of
 [SKILL.md](SKILL.md); everything SKILL.md says that is not named here
 still binds — Scope Check, File Structure, Task Right-Sizing, the plan
 header, Self-Review, and the Execution Handoff.
 ## Overview
 Write a plan that carries the decisions, not the keystrokes:
 decomposition, file structure, interfaces, constraints, and a precise
 contract per task. Assume the engineer is skilled and designs their own
 code and tests from a precise contract, but knows nothing about our
 codebase, toolset, or problem domain — every name, path, constraint, and
 behavior they must match is stated explicitly. DRY. YAGNI. TDD.
 Frequent commits.
 ## When This Shape Fits
 Use it when the spec composes more than one subsystem and a running
 end-to-end slice early is worth a longer total build: the value arrives
 as soon as real input reaches real output, and every later task widens
 something that already runs.
 Do not use it for a change to one subsystem, or when the whole point is
 to land the finished thing as fast as possible. This shape spends its
 first task on a slice that does almost nothing, and it spends planning
 effort on contracts and interfaces the task-by-task shape gets for free
 by writing the code out.
 ## Plan Document Header
 The header is SKILL.md's, plus one line directly under the **Goal:**
 line, which is how executors know which shape they are running:
 ```markdown
 **Plan shape:** skeleton-first
 ```
 ## Walking Skeleton First
 Task 1 builds the thinnest end-to-end slice through every subsystem the
 spec composes — real input to real output — before any task deepens a
 single layer; later tasks widen the skeleton.
 The test of a skeleton is that it runs. A first task that builds the
 data loader, the schema, or the config layer is a foundation, not a
 skeleton: nothing runs until something above it exists. A skeleton
 reaches the output — thinly, with one real case — through every
 subsystem the spec names.
 ## Task Contracts, Not Task Scripts
 A task states WHAT must exist when it is done, precisely enough that a
 skilled engineer can build it without asking you anything, without
 prescribing HOW:
 - **Goal:** one short paragraph naming the deliverable and its role in
  the feature.
 - **Success criteria:** concrete, checkable behaviors — exact commands
  to run and what they must show, the cases tests must cover (including
  failure cases), constraints that bind the implementation.
 - **Notes:** what the engineer needs and cannot discover alone — spec
  sections to read, files worth reading first, known pitfalls.
 The Interfaces block carries the exact names, signatures, and types;
 the success criteria carry the behaviors; the engineer supplies the
 code and the test design. TDD and frequent commits remain required.
 ## Task Structure
 ````markdown
 ### Task N: [Component Name]
 **Files:**
 - Create: `exact/path/to/file.py`
 - Modify: `exact/path/to/existing.py:123-145`
 - Test: `tests/exact/path/to/test.py`
 **Interfaces:**
 - Consumes: [what this task uses from earlier tasks — exact signatures]
 - Produces: [what later tasks rely on — exact function names, parameter
  and return types. A task's implementer sees only their own task; this
  block is how they learn the names and types neighboring tasks use.]
 **Goal:** [one paragraph — the deliverable and its role in the feature]
 **Success criteria:**
 - Run: `pytest tests/exact/path/to/test.py -v` — all tests pass; tests
  cover [the specific behaviors and failure cases, named concretely]
 - [observable behavior the deliverable must exhibit, with the exact
  command or input/output that demonstrates it]
 - [constraint that binds the implementation, copied from the spec]
 **Notes:** [spec sections to read; files to read first; known pitfalls]
 **Tier:** mechanical | judgment. Mechanical = the deliverable is fully
 specified by Files + Interfaces + success criteria above (most tasks in
 a well-specified plan are mechanical); judgment = multi-file
 coordination, debugging, or real design latitude remains. The
 implementer's model follows this field — mark it deliberately.
 **Commit:** one commit ending the task; message named here.
 ````
 ## No Vague Contracts
 Every contract must be checkable by someone who did not write it. These
 are **plan failures** — never write them:
 - "TBD", "TODO", "implement later", "fill in details"
 - Goals naming activity instead of a deliverable ("improve error handling")
 - Success criteria with no observable check ("works correctly", "handles edge cases")
 - Interfaces blocks omitting a name, signature, or type another task consumes
 - "Similar to Task N" (state this task's own contract in full — the engineer may be reading tasks out of order)
 - References to types, functions, or methods not defined in any task's Interfaces block
 ## Self-Review
 Run SKILL.md's Self-Review checklist, reading step 2 against "No Vague
 Contracts" above rather than "No Placeholders".
 ## Red Flags
 | Thought | Reality |
 |---------|---------|
 | "Task 1 is the data loader — that's the foundation" | A foundation is a layer. The skeleton runs real input to real output through every subsystem the spec names, thinly. |
 | "The skeleton can return a hardcoded value for now" | It may be thin, but the path must be real: real input, real wiring, real output. A hardcoded response tests nothing end to end. |
 | "A contract without the code is vague" | Vague is an uncheckable success criterion. Exact names, exact commands, exact expected output — no code. |
 | "I'll write the test code into the task to be safe" | The success criteria name the cases; the implementer designs the tests. Written-out tests are the task-by-task shape. |
 | "Skeleton-first is the better shape, so I'll use it here" | It costs total wall clock. Without more than one subsystem and a reason to want an early running slice, plan task-by-task. |