Plan-First Development

Code written before the problem is understood is rework wearing a disguise. This skill inserts a short, written plan between "I understand the request" and "I am editing files" — cheap to produce, cheap to correct, and the highest-leverage artifact in any nontrivial change. The agent drafts the plan, gets it approved (or self-reviews it against the quality bar when working unattended), and only then implements, in the order the plan committed to.

When to use this skill

• Any change that touches three or more files, or any file you have not read yet
• Requests with fuzzy acceptance criteria ("make it faster", "clean this up", "add exports")
• Work where a wrong assumption is expensive: migrations, deletions, public API changes
• Multi-session work that another agent or a human may pick up halfway through
• Skip it for true one-liners where the diff itself is the plan

Workflow

1. Restate the request in one sentence, naming the user-visible outcome. If you cannot, ask one clarifying question before doing anything else.
2. Read before you plan. Open every file you expect to touch and every caller of the code you expect to change. Note what surprised you — surprises found now are bugs prevented later.
3. Write the plan using the output format below. Order the steps so that each one leaves the codebase working; never plan a step whose failure strands the branch half-migrated.
4. Mark the risky step. Every plan has exactly one step most likely to go wrong. Name it, and state how you will detect failure early: a test, a log line, a manual check.
5. Define done. Concrete, checkable criteria: commands that must pass, behaviors to demonstrate, and things that must NOT change.
6. Get the plan approved — by the user when interactive, or by re-reading it against the quality bar when autonomous. Only then edit code.
7. Implement in plan order, checking off steps as they complete. When reality contradicts the plan, stop, amend the plan in writing, then continue. Silent deviation is the failure mode this skill exists to prevent.
8. Close the loop. After the last step, run the done-criteria verbatim and report which passed.

Output format

## Plan: <one-line outcome>

**Context.** What exists today, in 2-3 sentences, including anything surprising found while reading.

**Steps.**
1. <verb-first step> — files: <paths> — verify: <how you know it worked>
2. ...

**Riskiest step:** #<n>, because <reason>. Early signal: <check>.

**Done when:**
- [ ] <command or observable behavior>
- [ ] <thing that must remain unchanged>

**Out of scope:** <what this change deliberately does not do>

Quality bar

• Every step names files and a verification, not just an intention
• A stranger could execute the plan without asking the author anything
• The plan states what is out of scope — a plan without exclusions is a wish
• Steps are ordered so the build and tests pass after each one
• Fewer than ten steps; more than that means the request should be split

Worked example

Request: "add CSV export to the reports page."

Weak plan step: "Add export functionality." Strong plan steps:

1. Add a pure toCsv(rows) function in lib/export — verify: unit test covering quoted commas and empty cells
2. Add a /reports/export route streaming the CSV — verify: a request returns text/csv with the correct header row
3. Add an export button on the reports page wired to the route — verify: clicking downloads a file that opens in a spreadsheet
4. Out of scope: scheduled exports, column selection, other file formats

The weak version hides three decisions; the strong version has already made them.