The planning pass

You want the order app to export orders, and "improve exports" is as far as the idea has got. The planning pass — /prep — is one session that decides the shape of that work and builds none of it. Its entire output is plan files. (/prep <section> runs the same pass over one later area of an existing plan, rather than the whole project. There is also a whole-system variant for a wider design set, which you have to ask for by name; the ordinary pass does not load that depth.)

It is a separate session on purpose. Planning and building want different attention, and mixing them is how the first implementation choice becomes the architecture by accident.

The ordinary alternative

You write a planning note: the CSV goal, a couple of tests, go. If one person finishes it tonight, that note is enough and the pass below would cost more than it saves.

The friction starts when the work spans sessions, because a note leaves three questions easy to reopen — and each reopening is a decision somebody makes again, differently.

Nobody decides to let scope drift. It drifts one implementation choice at a time, and the choices are invisible because none of them was written down as a choice.

What the pass settles

The planning pass makes that division an explicit, inspectable act, and records the answers before any code exists. Approved fields become a human-owned constraint. Background processing becomes an explicitly rejected option for this change. Historical IDs get a later owner instead of slipping into the first build. None of that makes the plan smarter. What it does is let a session that was never in the room read the same agreement you did.

It works in a fixed order.

It declares on disk that this is a planning session, before it announces it. The declaration is one line — mode: prep — in the pointer block at the top of docs/PROGRESS.md, and a boundary check reads it: while mode: prep stands, writes outside the section being planned are refused, and so is any command that is not provably read-only. "Plan files only, no code" as a promise in prose is a promise the agent can forget. As a field on disk it is a condition other parts of the product enforce.

It settles the product's shape before asking anything about tools. Who it is for, where it runs, the one journey that has to work, the top three features, the top three explicit non-goals, single or multi user, online or offline. That set is capped deliberately: it establishes shape, not detail that will age before it is used.

It asks only the questions that change the plan. Section count, section ordering, structural choices, hard external dependencies, and what "done" means for the project as a whole. Anything that moves none of those is deferred to the session that will actually need it.

It writes four durable answers, then stops.

Later areas keep their place in the order and stay undetailed until their turn, because the sessions that run before them produce better evidence than anything available today.

Expanding one of them later writes its plan card and registers it in the master plan, and the registration is the half that matters. A plan file written by hand and never registered is an isolated file: the start command walks the pointer to the ordered plan, not the directory, so it never finds it and never guesses that it is the active work.

It ends by minting the pointer — the seven-field block at the top of docs/PROGRESS.md that the next session reads, carrying session 1's next action and the files it should read.

How a session entry is composed

Here is what the export becomes in the plan card — the whole of session 1, as it is written to disk:

## Session 1 — Filtered orders export as CSV

**Status**: pending

**Goal**: An authorized manager downloads the currently filtered orders as a CSV.

**Files to read**:
- docs/ARCHITECTURE.md
- docs/orders/decisions/export-fields.md
- app/orders/queries.ts
- app/orders/export/route.ts

**Build steps**:
1. Reuse the existing filtered-orders query; add no filtering behavior.
2. Serialize the approved columns through the existing serializer.
3. Put the route behind the existing manager check.

**Files to write/edit**: app/orders/export/route.ts, lib/csv.ts,
tests/orders/export.test.ts

**Verify**:
- A non-manager receives 403 and no file.
- The file holds exactly the orders the current filters show.
- The columns are the approved list, and no other.
- A comma or quote in a customer name does not break the row.
- An empty filter result returns a header-only file, not an error.
- The orders list page behaves as it did before.

**Output**: commit `feat(orders): CSV export for filtered orders`

The fields are composed in that order because the later ones are inferred from the earlier ones: the goal fixes what the session owns, the build steps decide which files it touches, and the files decide which checks are worth naming. What you read on the page is the finished entry, not the order in which it was worked out.

Two of the fields are proposed rather than requested from scratch. The file list is inferred from the build steps and offered for you to correct, named in your project's actual idiom — app/orders/ above, apps/<app>/views.py in a Django project — rather than as a generic placeholder. The check list is scaffolded from a recognized pattern when one matches, so a session about a webhook gets signature, tampering, duplicate-event and logging checks rather than "test it works". When no pattern matches, the pass asks you for two to four concrete checks instead of inventing vague ones.

Those six checks are the ones the close will walk, one by one, and they are written here — before any code exists — precisely so that the session cannot grade itself later.

An entry that grows past a set length is treated as a sizing signal and split. Length is usually two jobs wearing one name.

When to use it, and when not

That judgment is yours; the product cannot infer it from the size of the repository.

Limits

A plan is not proof. It names the checks that would establish the result; naming them passes none of them. The session that does the work still has to run them and report what it could not establish.

A detailed plan built on stale evidence is confidently wrong. Planning makes intent inspectable before work begins; it does not make the underlying facts current. The architecture can meet a constraint nobody knew about, and the check list can test the wrong condition. When new evidence breaks a load-bearing premise, the plan is what should change first, before the work depending on it continues.

A plan in files is not a better plan. What the pass establishes is narrower than that, and more useful: the agreement exists somewhere a session that was not present for the discussion can read it.

Next

With the shape settled, the next unit is one piece of it: the bounded session.