# Plan Execution

> Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved.

- Skill: `swestash/plan-execution` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add swestash/plan-execution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/swestash/plan-execution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SWEStash (https://skillmd.com/u/swestash)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/swestash/plan-execution

---


# Plan Execution

Execute an approved plan without silently drifting from it or claiming
unverified progress. A plan's value survives contact with reality only if
execution (a) proves each step actually worked and (b) notices when the plan's
assumptions stop holding. This skill starts where `feature-planning` ends: a
plan exists and is approved. If there is no plan yet, that's planning work —
route there first.

## ⛔ The Iron Law

**Never mark a checkpoint done without fresh verification evidence.**

A checkpoint marked done is a completion claim; `verification-before-completion`
governs each individual claim, and this skill applies that same gate at the plan
level — declared up front, per batch, with the evidence recorded. "The code is
written" is not "the checkpoint is done."

Quoting that law here is not the same as applying it. **Invoke
`verification-before-completion` at close-out** (Step 6) — carrying its Iron Law
inline makes the gate feel already satisfied, which is exactly how plans get
closed on unverified checkpoints and unreconciled docs.

## Workflow

### Step 1: Load the Plan and Define Checkpoints

Read the *entire* plan before executing any of it — later phases change how you
do earlier ones. Group the tasks into **checkpoints**: coherent batches (typically
3–5 tasks or one milestone) that are independently verifiable. For each
checkpoint, write down **before starting it**:

- the tasks it covers,
- the **verification**: the concrete command or observation that will prove it
  works (tests pass, endpoint responds, migration applies cleanly, doc renders).

A checkpoint whose verification you can't name isn't a checkpoint — split or
rescope it until it has one.

### Step 2: Execute a Batch, Logging Drift As You Go

Work the checkpoint's tasks. Any deviation from the plan — a different approach,
an extra task, a skipped step, a surprise — goes into a **drift log** the moment
it happens, even when the deviation is an improvement. Undocumented "better
ideas" are how a plan dies without anyone deciding to kill it.

### Step 3: Verify the Checkpoint

Run the verification you declared in Step 1 — fresh, in full, reading the entire
output (see `verification-before-completion` for the gate function). Only then
mark the checkpoint done, recording the evidence next to it: the command and its
observed result. A failed verification means the checkpoint stays open — fix and
re-verify; two consecutive failed checkpoints are a re-planning trigger, not a
push-through-it signal.

**Report each checkpoint in exactly one of two states: done with its evidence, or
explicitly not done. There is no middle state** — no "mostly done", "basically
working", "should work", or "done pending tests". Say this rule when you declare
the checkpoints, so the reader knows what a status report from you will and will
not contain. A half-state is how a false "done" enters the record.

**The checkpoint commit is part of this step, and it is checked.** A commit is the
first irreversible thing a plan produces, so it gets the same treatment as the
checkpoint claim: **invoke `verification-before-completion`** for the publish gate
and **`git-workflow`** for the message.

**Exit condition** — name both, by name, in the response where you commit:
*"Checkpoint N verified by `<command>`. Invoking `verification-before-completion`
on the staged diff, then `git-workflow` for the message."*

Do not paraphrase what those skills would check and call it done. Reproducing
their rules here is exactly how a plan accumulates twelve unreviewed commits with
a gate that felt "already satisfied" every time — you have their content in
context, which is what makes skipping the call feel free. If you can name the check
you are supposed to run, you can name the skill that owns it.

**The plan's vocabulary does not travel with the commit.** Checkpoint IDs, phase
names, task codes, finding numbers, and drift-log entries are *your* working
context — they name conversations, not code. They may appear in a commit message,
comment, or doc **only if the plan itself is a tracked file in this repo**; a plan
living in a scratchpad, a chat, or a gitignored directory defines nothing a reader
can look up. Otherwise write what the change means:

- ✗ `feat: complete CP2.3, Phase 2 done` ✗ `// fixes finding #12 from Phase 1`
- ✓ `feat(sync): add delta detection by content hash`

This is the one leak plan execution is uniquely prone to, precisely because the
vocabulary is loaded and fluent in context at the moment the message gets written.

### Step 4: Drift Check Before the Next Batch

At every checkpoint boundary, compare state against plan:

- **Scope drift** — doing work the plan doesn't contain
- **Assumption drift** — the plan assumed X; reality turned out to be Y
- **Estimate drift** — checkpoints taking a multiple of what was planned

Small drift: record it and continue. Structural drift: stop — Step 5.

### Step 5: Re-Plan When Triggered — Don't Improvise

Stop executing and go back to planning (with the user, via `feature-planning`)
when any of these fires:

- an assumption the plan rests on turns out to be false
- a task reveals the chosen approach won't work
- accumulated unplanned work is a large fraction of the remaining plan
- two consecutive checkpoints failed verification
- you catch yourself thinking "the plan didn't anticipate this, but I'll just…"

A **structural question the plan didn't answer** fires this too: where a piece
of state lives, whether to add a table, column, service, module, store, or
config key. Don't settle it inline — **invoke `data-modeling` (data shape) or
`architecture-design` (structure and boundaries)** and let it run its inventory
of what already exists. These decisions arrive disguised as implementation
details, and they're the ones the plan is least able to absorb silently:
persistent constructs outlive the plan that introduced them.

Re-planning openly is cheap; silently executing a plan that no longer matches
reality delivers the wrong thing with perfect discipline. Sunk progress is not a
reason to continue — the remaining work costs the same whether or not you admit
the plan changed.

### Step 6: Close Out

Invoke `verification-before-completion` and work its gate over the plan as a
whole. Finish with a final end-to-end verification (the whole, not just the last
part), reconcile plan vs as-built from the drift log, and report per checkpoint:
done **with its evidence**, or explicitly not done. No middle state.

Reconcile the **documentation** here too, across the plan's whole surface rather
than per checkpoint — a plan renames a flag in checkpoint 2 and adds an endpoint
in checkpoint 5, and each looked locally complete while the README fell behind
both. Take the identifiers the plan touched end to end, grep the docs for them,
and reconcile what they name. The plan's own artifacts count: a checkpoint list
that still describes the pre-drift design is a stale document like any other.

## Rationalizations to Reject

| Excuse | Reality |
|--------|---------|
| "The change obviously works; running the check is overhead" | The check takes seconds; an unverified checkpoint poisons every checkpoint built on it. |
| "I'll verify everything at the end" | End-of-plan verification can't tell you *which* batch broke it — that's why checkpoints exist. |
| "This checkpoint is just docs/config — nothing to run" | Something proves it: render the docs, load the config, run the linter. |
| "The docs can come after the plan lands" | The plan changed what the docs describe; landing it leaves them actively wrong, and nobody re-derives the whole surface later. Reconcile at close-out. |
| "I already have the Iron Law in context, invoking the gate is redundant" | Quoting a law isn't running the gate. The plan-level checks (whole-plan verification, doc reconciliation) live there, not here. |
| "It's a mid-plan commit, the real gate is at close-out" | Commits are permanent when they're made, not when the plan ends. Close-out can't un-publish what checkpoint 2 already pushed. |
| "The checkpoint number gives the commit useful traceability" | Only if a reader can resolve it. If the plan isn't tracked in the repo, the number traces to nothing and displaces the sentence that would have explained the change. |
| "Everyone on this plan knows what CP2.3 means" | Everyone in this session does. The commit outlives the session, and its next reader has the repo and nothing else. |
| "The plan is outdated here; I'll adapt as I go" | That's drift. Log it; if it's structural, stop and re-plan — don't decide alone silently. |
| "This is an implementation detail, not an architecture decision" | Anything that persists — a table, a column, a config key, a shared module — is structure, whatever task it arrived under. Route it to the design skill. |
| "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
| "Marking them done unblocks the team; we'll backfill verification" | A false "done" misinforms every decision downstream. Report the honest state instead. |

## Red Flags — Stop and Check

- Marking several checkpoints done in one sweep, none with evidence attached.
- You can't say what command verified the last checkpoint.
- "Should work" / "looks done" appearing in your status report.
- Mid-execution, you're building something the plan never mentioned.
- You're about to add a persistent construct (table, column, config key, shared
  module) that the plan never named — and you haven't checked what already exists.
- You've stopped consulting the plan and are working from memory.
- You're committing at a checkpoint boundary and haven't read the staged diff.
- A phase name, checkpoint ID, or finding number is about to enter a commit
  message, a code comment, or a doc — and the plan isn't a tracked file.

## Cross-Skill References

- `feature-planning` — creates and (on re-plan) revises the plan this skill executes
- `data-modeling` — where a schema question surfaced mid-execution belongs
- `architecture-design` — where a structural or boundary question belongs
- `verification-before-completion` — the per-claim evidence gate each checkpoint applies, and the publish gate on every checkpoint commit
- `tdd-workflow` — how the implementation tasks inside a batch get built
- `git-workflow` — writes the checkpoint commit (Step 3); the evidence belongs in the message
- `code-reviewing` — review at checkpoint or close-out, before "done" is claimed