execute-plan · diff
git:20261008.8e403b1 to git:20261026.069feb8
25 added, 11 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: execute-plan
description: >-
Execute an approved plan from thoughts/plans/ to completion — every phase, every check, every
acceptance criterion — and stop only when DONE or BLOCKED. Use when someone says "execute the plan",
"implement the plan", "build it" after a plan was approved, "start building", or points at a file in
thoughts/plans/. Medium/large work without a plan → /dev-skills:write-plan first.
---
# Execute Plan
Carry an approved plan through to working, verified code. The plan is a contract: you either satisfy it or show exactly why it can't be satisfied.
## Input
A plan in `thoughts/plans/` (from `/dev-skills:write-plan`). No plan and the work is medium/large → write one first. No plan and the work is small and clear → state the acceptance criteria in one line each, then run under the same contract.
## The Contract
Approval of the plan is the only gate. From then on you own delivering it, and a run ends in exactly one of two states:
**DONE** — every phase implemented; every phase check green; full test suite, typecheck and lint with no new failures against the baseline you recorded at the start; every acceptance criterion verified with cited evidence. For UI criteria, that means you ran `/dev-skills:qa-test` yourself and it passed.
**BLOCKED** — the contract can't be satisfied without something only the user can provide:
- a permission, credential, or access you don't have (and the plan's pre-flight blockers didn't cover)
- a harness that can't be made runnable by you — a check needs a human step with no bypass
- a plan premise that turns out false, with no resolution that stays within the plan's intent
- a risky or irreversible action that needs explicit confirmation: anything against shared, staging or prod environments, or outward-facing (pushing, opening PRs, deploying, messaging). Local/dev DB migrations, resets and seeds the plan's checks call for are in-contract.
- the same check still failing after 3 genuinely different fix attempts
Before stopping BLOCKED, finish every item that doesn't depend on the blocker.
- **Everything else is yours to resolve.** Renamed symbols, moved files, different signatures, a missing import, a choice between two reasonable implementations, a scope-adjacent decision where one option clearly fits the plan's intent — decide, record it under `## Deviations` in the plan file (what the plan said, what you did, why), and keep going.
+ **Everything else is yours to resolve.** Renamed symbols, moved files, different signatures, a missing import, a choice between two reasonable implementations, a scope-adjacent decision where one option clearly fits the plan's intent — decide and keep going.
+ ### The Decisions log
+
+ Every call the plan didn't make — a departure from it, or a gap it left open — goes under `## Decisions` at the end of the plan file, as you make it. This is what the reviewer reads instead of the diff, so write it for someone who wasn't in the session:
+
+ ```
+ ## Decisions
+ 1. When a Stripe sync fails, the job retries 3× and then gives up silently — you'd only notice from missing invoices. Plan didn't say. Alt: alert after 3 fails. (unsure)
+ 2. Invoices are keyed by Stripe's id, so re-syncing updates rows instead of duplicating them. Plan said `uuid` pk. (sure)
+ ```
+
+ - One line each, plain words: what happens as a concrete scenario → what the plan said (or "didn't say") → the alternative not taken → `(sure)` / `(unsure)`.
+ - Log what a reviewer would want to know: behavior, data shapes and storage, contracts and error behavior, dependencies, retries/timeouts, scope. Skip trivia — names, imports, file moves.
+ - At final verification, reorder least sure first.
+
### How turns end
A message without a tool call ends your turn, and the work stops there. While the contract is open, don't end a turn in any of these ways:
1. A summary of what's done that announces the next step instead of taking it.
2. An offer to continue "unless you'd prefer otherwise".
- 3. A list of decisions for the user when none of them blocks the remaining work — decide, log under Deviations, continue.
+ 3. A list of decisions for the user when none of them blocks the remaining work — decide, log under Decisions, continue.
4. Reporting because a phase finished, a milestone landed, or the turn got long.
Status notes are welcome — put them in the same message as your next tool call. Before any message without a tool call, read the plan's checkboxes and your todo list: open items and no stated blocker means keep working. Background work whose result you depend on (test runs, sub-agents) has to finish and be read before you can call the work DONE. Long-running servers are fine — note them or stop them.
## Process
### 1. Load the contract
Read the plan completely, the shape doc it links (acceptance criteria live there), and the files each phase touches. Build a todo list: one item per phase, plus final verification and each acceptance criterion.
Resuming? Existing `[x]` marks in the plan are done — start from the first unchecked item; re-verify earlier work only if something contradicts it.
Verify the plan's **Pre-flight blockers** are cleared (key present, seed runs, auth bypass works) — plus browser MCP reachability if there's a UI layer or UI criterion. Record a baseline of the test suite, typecheck and lint. If a pre-flight item isn't in place, that's BLOCKED before any code — report it now, not after three phases. Pre-existing failures in the baseline are listed in the report, not fixed.
### 2. Execute phase by phase, layer by layer
For each phase:
1. **Implement** the changes, following existing patterns.
2. **Prove** — run the phase checks. They are agent-runnable commands; if one isn't, make it one (a script, a curl, a seeded route) rather than skipping it.
3. **Fix** until green. Don't start a layer until the layer beneath it is proven — a UI bug is never debugged on top of an unproven API.
- 4. **Record** — tick each check `- [x]` in the plan file as soon as it passes, before running the next one; a phase is done when all its boxes are ticked. Never tick a check that hasn't passed in this run. Update todos, log any deviation.
+ 4. **Record** — tick each check `- [x]` in the plan file as soon as it passes, before running the next one; a phase is done when all its boxes are ticked. Never tick a check that hasn't passed in this run. Update todos, log any decision.
Then move straight to the next phase.
### 3. Final verification
- Full test suite, typecheck, lint.
- Every acceptance criterion from the shape doc, each with evidence: command output, query result, or qa-test finding.
- UI criteria → run `/dev-skills:qa-test` in agent mode. It fixes and re-tests up to its own limit; a criterion it can't get green is a BLOCKED item with its evidence.
### 4. Report
+ Decisions lead — they're what the developer hasn't seen yet.
+
```
Contract: DONE | BLOCKED
+ Decisions (least sure first — full list in the plan's ## Decisions)
+ 1. [what happens, as a scenario] — [plan said X / didn't say]. Alt: [not taken]. (unsure)
+ 2. ...
+
Acceptance criteria
1. [criterion] — ✓ [evidence: command/output, qa-test result, row]
2. ...
- Deviations
- - [plan said X → did Y — why]
-
- Defense deltas
- - [decisions made during implementation the developer hasn't seen: a new table, a changed
- failure mode, a different library — in plain words]
-
(BLOCKED only)
Blocker: [what, with evidence]
Needed from you: [the specific thing]
Already done: [phases/items complete]
```
## Rollout discipline
Check the plan's Rollout & Rollback block before coding:
- **"Direct deploy, no flag"** — don't introduce a flag mid-implementation. If the change turns out riskier than planned (critical path, bigger blast radius), that's a premise change: log it and, if it breaks the plan's intent, BLOCKED.
- **"Flag"** — one named flag for the whole feature, at the user-perceived boundary. No per-phase or per-layer flags.
- **"Expand-contract"** — execute through expand + migrate, then end DONE with "contract phase pending deploy" in the report. The contract phase needs the expand deployed first, so it never runs in the same session; never collapse expand and contract into one PR.
- **"Both"** — flag the consumer, expand-contract the schema/API. Flags wrap code, not storage.
See [write-plan/references/rollout-primitives.md](../write-plan/references/rollout-primitives.md) for the full decision tree.
## Working guidelines
- Read before editing — full files for small ones, targeted sections for large ones.
- Follow the codebase's existing patterns; consult [references/software-design-philosophy.md](references/software-design-philosophy.md) and watch for shallow modules, information leakage, pass-through methods.
- Keep changes inside the plan's scope — no unrelated "improvements".
- Sub-agents for exploration (reading tests and related modules in parallel), not for writing the code.
- Acceptance criteria are the user's: if one looks wrong, verify what's specified and flag it in the report; don't edit it.
## Handoffs
- - DONE on customer-facing work → offer `/dev-skills:explain` on the shipped diff, seeded with the Defense deltas, so the developer can explain and defend what shipped.
+ - DONE → offer `/tap-skills:blast-radius` for an independent review before merge: it checks the Decisions log against the diff and finds the calls it missed.
+ - DONE on customer-facing work → offer `/dev-skills:explain` on the shipped diff, seeded with the Decisions, so the developer can explain and defend what shipped.
- BLOCKED because the plan itself is wrong → `/dev-skills:write-plan` with the evidence.