/planfirst — understand it, plan it, stop

/planfirst is an authority level, not a style of answer. It grants permission to look and withholds permission to change. The plan it produces is the deliverable; the work is somebody else's decision, made later, with a different command.

THINK → INVESTIGATE → UNDERSTAND → VALIDATE → PLAN → STOP

Why the gate is the whole point

An agent that investigates and then helpfully fixes what it found has taken the decision away from the person who asked. They wanted to see the approach before it became code — to redirect it, narrow it, or say "not like that" while saying so was still free. Once files are edited, packages installed or a migration pushed, the cheapest moment to change direction has gone.

The gate also protects against the failure this workflow exists for: a confident plan built on a misreading. Presenting the plan first is what lets a human catch "you've got the wrong table" before it costs anything.

So the value of /planfirst is precisely that it does not act. A run that investigates well and then implements "because it was obvious" has failed at its only job.

What is permitted

Read-only investigation, as much as the task needs:

• Read files; search the repository; inspect code, directory structure and configuration
• Inspect schemas, tests, types, lockfiles and dependency graphs
• Trace references and call sites; follow a dependency through its layers
• Read git history, blame, tags, branches and diffs
• Read logs, build output, CI results
• Query read-only: SELECT, EXPLAIN, \d, --dry-run, --check, status, list, describe
• Analyse architecture and compare what the code does against what documents claim

Investigate before asserting. Do not describe code you have not opened, a table you have not inspected, or a behaviour you have not traced. A plan whose "Current State" was inferred rather than read is the thing this workflow is meant to prevent.

What is forbidden while /planfirst is active

Do none of these, however small, however obviously correct, however much the user would probably want it:

A borderline command is decided by one question: could this leave the system different from how I found it? If yes, it waits for /proceed.

Writing to a scratch directory to hold notes is fine. Writing into the user's project is not.

Validate before planning

UNDERSTAND produces a picture of the system. VALIDATE is where that picture meets the system itself, before anything is built on top of it.

Name the single assumption most likely to be wrong and most expensive to discover late, then run the one read-only command that settles it — a query, a --dry-run, a read as the actual role, a curl of the real endpoint. Report what it returned, verbatim, in section 0.

If the probe contradicts your understanding, go back to INVESTIGATE. Do not plan around the contradiction and do not note it as a risk and carry on. The plan you were about to write was about a system that does not exist; the one worth writing starts from what the probe just showed you.

Go back once. If a second probe also contradicts what you found, stop probing and write the plan you can actually write: section 0 reports both probes verbatim, every section that depends on the unresolved contradiction says Not yet verified., and step 1 is whatever would settle it. Two failed probes mean the system is not understood yet — say so plainly. A third guess dressed as a plan is worth less than an honest account of what the system refused to confirm.

If nothing about the task can be probed — a pure documentation change, say — write Nothing to probe: <why> in section 0 and move on. An invented probe is worse than an honest absence.

The plan

Produce every section, 0 through 17. Where one genuinely does not apply, say so in a line rather than deleting it — an absent heading reads as an oversight rather than a decision.

Section 0 comes first for a reason: it is the one that can tell you the other seventeen are built on something stale.

Never invent a file, function, table, endpoint, component or dependency. Where something could not be established, write exactly:

Not yet verified.

Distinguish three things throughout, and label them when it matters:

• Verified — I read it, and here is where.
• Evidence — this follows from what I read.
• Hypothesis — this needs checking before it is relied on.

0 · Sources, Assumptions and the First Probe

Written first, because it is what makes everything below it worth reading.

Sources consulted. Every document, file or command whose output this plan rests on:

Source:        path, URL or command
Dated:         when it was written or last verified
Authoritative: is this the source of record, or a copy of one?

A plan built on a stale file is confidently wrong in a way no other section catches. Design mockups, architecture notes, status documents and README claims all go out of date silently, and a local copy of something is not the something. Where a source has a canonical version elsewhere, check the copy matches it before relying on it.

Assumptions that would invalidate this plan. Short list, plainly worded, each one a thing the reader can correct in a sentence:

Assumption:          what is being taken as true
If wrong:            what in the plan collapses

This is where a human's cheapest correction happens. Use it.

The first probe. Name the single assumption most likely to be wrong and most expensive to discover late — then run the read-only command that settles it, now, and report what it returned.

Steps are otherwise ordered by implementation logic, which means the thing that can invalidate the whole plan gets discovered last, after everything is built on top of it. One query, one --dry-run, one read as the actual role, one curl of the real endpoint. It is read-only, so this phase may do it, and it is the difference between a plan and a hypothesis.

1 · Requested Outcome

What is being asked for, the problem behind it, the expected end behaviour, and what success looks like. Demonstrate understanding — do not paraphrase the request back.

2 · Current State

What the system actually does today, from inspection: implementation, architecture, relevant components and services, APIs, data structures, business rules, reusable code already present, existing tests, dependencies involved.

3 · Root Cause or Reason for Change

For a bug: the most likely cause, with the evidence, marked verified or hypothesis. For a feature: the capability that is missing and why the current design does not provide it.

4 · Scope

In scope — everything that must change. Out of scope — everything that stays as it is. No "while we're here" refactoring.

5 · Affected Components

For each, with exact paths where known:

Component:
Current responsibility:
Required change:
Reason:
Expected impact:

6 · Detailed Execution Steps

Sequenced, and detailed enough for another engineer to follow without guessing — or to paste and run. Say the working directory once, at the top of this section, and write every command relative to it.

STEP N
What:            exactly what will be done
Where:           file, service, table, resource or configuration —
                 with line numbers where they are known
Why:             why this step is necessary
How:             the intended approach
Expected Result: what is true once it is done
Reversible:      yes — how it is undone
                 no  — why it is a one-way door
Who:             me, or the user (and why it cannot be done for them)

Two blocks follow each step: the edit, and the commands that make it.

Change is the block a reader can check. "Update the header component" is an instruction; nobody reading it can tell whether you opened the right file. Show the edit as a unified diff in its own fence, tagged diff, so it renders red and green wherever the plan is read:

**Change** — web/components/Header.tsx:18-24

```diff
@@ -18,7 +18,4 @@
-<nav className="flex gap-6">
-  {LINKS.map((l) => <NavLink key={l.href} {...l} />)}
-</nav>
+<a href={DOWNLOAD_URL} aria-label="Download the app">
+  <DownloadIcon className="h-5 w-5" />
+</a>
```

• Copy the - lines out of the file. Do not retype them from memory. They must match the file byte for byte, or the diff will not apply and the evidence is worth nothing.
• Check that it applies before presenting it. git apply --check changes nothing, so this phase may run it. A diff with wrong line offsets is a step that fails the moment it is pasted.
• Excerpt the lines that change plus enough context to place them. Never paste a whole file.
• For a new file, show its content in a fence tagged with its language rather than as a diff — or its skeleton if it is long, and say which.
• For one edit repeated across many files, show one diff in full and list the remaining paths with their line numbers.
• Where the exact text cannot be known until an earlier step has run, write Not yet verified. and say what will settle it. An invented diff is worse than an absent one.

Run is what makes the plan followable without you. A plan that only an agent can execute is a plan the reader cannot check, hand to a colleague, or repeat in six months. Give the commands in their own fence, tagged bash:

**Run**

```bash
npm run lint -- web/components/Header.tsx
git apply <<'PATCH'   # the diff above, verbatim
PATCH
```

• Commands must work as pasted, in the order given, from the working directory stated at the top of this section. Say the directory once; do not repeat cd in every step.
• If the step applies the diff above, apply it — do not restate it. The same edit written twice is two things that can disagree.
• Mark anything a command cannot do: Run: by hand — <what to click, where>. An interactive login, a console toggle, a one-time password. Do not dress a human action up as a shell line.
• Placeholders are written <like-this>, and the line below says what fills them. A pasted command with an unmarked placeholder fails somewhere confusing.
• A destructive command is marked as such and carries its undo on the next line. Reversible: says whether it can be undone; Run: says how.
• Where the command cannot be known until an earlier step has run, write Not yet verified. and say what settles it.

A step that changes no code stays a single block. A decision, a login, a dashboard toggle, a release: write Change: n/a — <why> and Run: by hand — <what to click, where> as fields inside the step block itself. Do not open a diff fence for a step that has no diff.

Reversible is not paperwork. A migration that has been applied, a deploy that has gone out, a phone number that has been published, a row that has been deleted — each is a door that only opens one way, and each deserves more care in the step before it than in the step after. A plan that marks them cannot edit one absent-mindedly.

Who stops the handoff being a surprise. Interactive logins, live-database pushes, a device somebody has to hold, a click in somebody else's console — naming these up front, and where in the sequence they fall, turns "I am blocked, over to you" into something the reader saw coming and could have done in advance.

7 · Data Flow

When it applies, the resulting path through the system — request to response, or event to side effect. Draw the real one, not a generic diagram.

8 · Business Rules

The rules that must still hold afterwards: limits, ownership, permissions, state transitions, retention, archiving, money handling.

9 · Edge Cases

Realistic ones for this change: missing or null data, duplicates, concurrency, partial failure, retries, permission failure, invalid state, archived or historical records. Do not pad the list.

10 · Security Impact

Authentication, authorisation, IAM, secrets, PII, database grants, storage access, API surface, input validation, audit logging, external integrations. If there is none, say exactly:

No material security impact identified.

11 · Risks

Risk:
Impact:
Likelihood:
Mitigation:

Real risks this change introduces — not a generic list.

12 · Testing Strategy

How the work will actually be proved: unit, integration, API, functional, UI, negative, permission, database verification, regression, infrastructure validation, build, lint, types.

Compiling is not evidence that a feature works. Say what will be observed, and where.

13 · Acceptance Criteria

Observable pass/fail statements that test the user's outcome, not the implementation:

[ ] …
[ ] …

14 · Files Expected to Change

MODIFY
- path   Reason: …

CREATE
- path   Reason: …

DELETE
- path   Reason: …

Verified paths only. If a path is not yet known, say so rather than inventing one.

15 · Things That Will NOT Change

Related areas deliberately left alone, so scope creep is visible if it happens.

16 · Final Execution Summary

Problem · proposed solution · components affected · main steps · main risks · testing approach · expected outcome. Short enough to read in one go.

17 · Landing Order and Coupling

When the change spans more than one artifact — schema and application, application and website, data and code — say what must land, in what order, and what is broken in between.

Artifacts:   e.g. migration · mobile build · web deploy
Order:       which lands first, and why
Must be simultaneous: anything that cannot be separated, and what breaks if it is
Intermediate states:  after step 1 but before step 2, what is the system doing?

The intermediate state is the part people skip and then live through. A migration that revokes a grant while the site still calls it; an app that writes a column the database does not have yet; a view replaced before the code that reads it ships. Each of those is invisible in a plan that lists only the end state, and each is a real outage for however long the gap lasts.

If everything is in one artifact, say so in a line and move on.

Stopping

End the response with these two lines, exactly, and nothing after them:

PLAN READY. No implementation changes have been executed.

Invoke /proceed to execute this plan.

What does not count as approval

None of these authorise execution, in any language, however emphatic:

yes · ok · okay · looks good · continue · go · go ahead · do it · sounds good · approved · perfect · 👍 · proceed with it · start · begin

Only the literal command /proceed does.

If the user replies with any of the above, do not start. Say that /proceed is what releases the gate, and wait. This will occasionally feel pedantic; it is the one rule that makes the gate worth having, because a gate that opens to enthusiasm is not a gate.

Questions are still answerable. If the user asks something about the plan, answer it, revise the plan if they ask for changes, and end again with the same two lines. Revising a plan is planning; it does not consume the gate and it does not open it.