How to plan

A plan gets read far more often than it gets written, and the person executing it knows less than you do right now, and it's committed to before the world stops moving. So build the correctness into the shape of the plan rather than into the planner's memory. Any constraint you keep only in your head is one the implementer is going to rediscover, usually at the worst possible moment. This is MANIFESTO.md pointed at planning itself, which the manifesto calls the process layer (tenet XXV) that the code tenets fall back on. The objective hasn't changed, only the wording for this phase: minimise what the implementer must reconstruct to make the change correctly, subject to bounding the blast radius of the irreversible and cross-team parts of the work. When two of the moves below pull against each other, you don't resolve it with a slogan. You resolve it by asking who controls the input and how wide the blast radius is. None of it is free.

Bound the unknown before you commit to it

An estimate given before the unknowns are bounded is a number you invented; the underspecified requirement and the cross-team dependency are the hostile inputs of planning.

A plan inherits its correctness from inputs it doesn't control. A stakeholder's half-formed want. An API another team hasn't built yet. A "we'll figure it out". Treat each one as hostile until it's proven otherwise (tenet IV). Don't trust what the request asserts it needs - re-derive what it actually needs, and bound the size of every unknown before you spend an estimate on it. "It looked fine on the slide" is a value you accepted without re-deriving what it actually needs, and that's exactly how the wrong plan ships.

A feature: a one-line spike to settle the open question, then size the known work vs an estimate that silently prices in a guess nobody flagged.
A migration: confirm the data has the shape you assume before you commit a cutover date, rather than meeting the real null-rate at 2am, mid-cutover.
A dependency: a written contract and a date you verified vs "they said it'd be ready", an authority the other side merely asserted about itself.

Tension: This pulls against simplicity (tenet XXI). Don't spike every line into the ground; bound the unknowns, not the knowns. The questions worth a spike are the ones where being wrong moves the date or the approach. Settle those, assume the rest, and write down what you assumed.

Ask yourself: What's the worst the unbounded part could turn out to be, and have I bounded it before anyone treats my estimate as a promise?

Anchor every fact to one owner; kill the ambient context

A plan that depends on what was "discussed" depends on a thing the reader cannot reach; show where each constraint comes from.

Globals are invisible state that gets mutated somewhere else, and a plan has them too. The decision made in a meeting. The constraint living in someone's memory. The "as agreed" with no link attached. Each one is an ambient dependency with no override point (tenet II), so the reader has to reconstruct invisible context before they touch anything. Give every fact in the plan exactly one authoritative owner and link it (tenet XIV). Everything else in the document is a view of that fact, marked as derived - not a second copy that's going to quietly disagree with the first.

A constraint: "must stay under the 200ms edge budget, see [perf doc]" vs "needs to be fast", a fact with no owner and no number.
A decision: a linked design record that says why this approach won vs a conclusion with no trail, re-argued at every standup.
A dependency's status: the tracker is the single truth, not tracker plus Slack plus a spreadsheet, three beliefs about the same work.

Tension: This is paid for in brevity. Linking every fact bloats the plan toward a citation swamp. Anchor the load-bearing facts, the ones a wrong assumption about would change the work, and let locality (tenet I) carry the obvious rest.

Ask yourself: If two versions of this constraint disagreed at 3am, which is authoritative, and can the implementer reach it from the plan alone?

III

Write "done" once, as the contract

Define the finished state as acceptance criteria at the top, so "is it done?" cannot be re-litigated at review by everyone who forgot.

Validation answers "is this okay?" at review time and then throws the answer away, so the question gets asked again and some people answer it differently. Parse instead (tenet III). Turn the fuzzy want into a narrower, checkable thing once: a list of criteria that's the contract between planner, implementer, and reviewer (tenet XV) and the executable test of done (tenet XXIV). Model the work as one state rather than a soup of booleans. It's triage | ready | in-progress | blocked | done, so "shipped but not reviewed" is untypeable instead of being an argument.

A feature: "the button is disabled on submit and the request is deduped by id", a criterion you can check vs "handle double-clicks somehow".
A bugfix: "a regression test reproduces the original report and now passes" vs "fix the crash", done when someone feels it is.
A spike: "produces a decision record with a recommendation and the rejected options". A spike with no defined output is a meeting.

Tension: This cuts the other way against discovery. Some work genuinely can't state its done-criteria up front. Then the criterion is the spike's output (above): name what the spike must produce, and don't let "exploratory" mean "unbounded".

Ask yourself: Could a stranger confirm this is done from the criteria alone, without me in the room, and is every criterion something they can actually check?

Cap the scope; the uncapped plan is the OOM

Anything whose size the requester or the discovered work controls grows without limit unless you give it a ceiling.

"Improve performance". "Clean up the module". "Support all the cases". Each one is caller-driven growth with no bound on it, which is the planning version of the unbounded queue that fails later in production (tenet VII). Cap the scope explicitly and split the moment the work crosses the ceiling. And reach for fewer states before you reach for more (tenet XXI): the issue you don't open can't go stale, and the flag you don't add can't be misconfigured.

A feature: "ship search over titles; full-text over bodies is a separate issue" vs "add search", which quietly grows to own indexing, ranking, and i18n.
A refactor: a bounded slice with its own done-criteria vs "tidy as we go", the scope that eats every sprint it touches.
A backlog: delete the stale ticket ("we might do it" is what the archive is for), rather than a graveyard nobody dares close.

Tension: This pulls against YAGNI (tenet XXI). A scope ceiling is not a missing feature; it's the difference between a plan and a liability. Cap what external input or discovered work can grow; don't pre-limit the genuinely fixed. YAGNI applies to features, not to limits.

Ask yourself: What's the maximum this can grow to, who controls that growth, me or the requester, and where does it split when it crosses the line?

Separate the decision from the doing

Make "which approach, and why" a standalone, reviewable artefact; make the implementation the thin part that merely realises it.

The catastrophic verbs of planning - commit to an architecture, schedule the migration, promise the date - get their danger from being fused to their reasoning. A plan that decides the approach while it executes can never be reviewed without paying to build it, so you end up under-scrutinising the exact decision that most needs proof. Split them (tenet XI). A design doc or spike is decideApproach(constraints) -> plan, a pure thing you can hammer with review and four-eyes at zero cost, and the implementation is the small wrapper that runs an approved plan. This seam is what makes dry-run, sign-off, and a clean rollback possible. They all hook in right here.

An architecture: a written design with the alternatives and the tradeoff, reviewed before a line is cut vs an approach that only exists once it's half-built and expensive to change.
A migration: a reviewable manifest of exactly what moves, dry-run first vs fusing the decision and the apply into one irreversible step (tenet XI).
A risky change: a named approver signs the plan before it runs (tenet XXV), not an approach waved through by whoever happened to merge it.

Tension: The split lets the plan go stale (a TOCTOU window, tenet IX); the world moves between deciding and doing. Pin the plan to the assumptions it was computed against and re-check them at kickoff. Things change between sign-off and kickoff. The API shipped with a different shape, the requirement shifted under you, the team reorganised. So kickoff has to re-confirm the assumptions the plan leans on before it runs, otherwise you go and execute a decision that the facts have already overtaken. Only skip the seam where the change is cheap and you can undo it - a design doc for a one-line fix you can roll back is just ceremony.

Ask yourself: Can I review this decision to death without having built it, and will the assumptions it rests on still hold when the doing starts?

Sequence for reversibility; refuse the big bang

Order the work so every increment is independently shippable and revertible; the irreversible one-shot is a bet you've forbidden yourself from losing gracefully.

The plan is going to be wrong about something. The only thing in question is how much that wrongness costs. Sequence for cheap retreat (tenet XX): expand to contract, behind a flag, ramped, with each step leaving a state you can run and roll back. The big-bang rewrite and the drop-and-rename cutover aren't bold. They're plans with no losing move in them, and at some point you are going to need a losing move. Getting reversibility right at plan time is the thing that lets you ship into reality, watch (tenet XVIII), and back out again without an archaeology dig.

A feature: flag-gated, ramped 1% to 100%, so a bad release is a config toggle, not a launch you can only undo by shipping again.
A schema change: expand, backfill, dual-write, switch reads, then drop, every intermediate state runnable vs the one-transaction cutover that's a cliff.
A model swap: shadow on live traffic and promote on evidence, write to a new partition and swap pointers, not overwriting the only thing that could have saved you.

Tension: This trades against simplicity (tenet XXI) and the duty to forget. Every seam and flag is clutter until something uses it, so add one only when you can name the second real thing that will go through it, with an owner and a sunset. And reversibility runs into deletion duty: keep increments rollback-able, but decide retention per data class in the plan instead of defaulting to keep-forever.

Ask yourself: When this is wrong in a year, is the fix a scalpel or a demolition, and can I name the second thing that will use any seam I'm adding?

VII

Name the failure modes and the degraded path in the plan, not the incident

State up front how this can fail and what it costs, and for every risky dependency name the fallback; an unlisted risk is a wrong state that learned to hide.

When a risk stays invisible right up until it fires, the plan is a happy-path lie and the implementer ends up inheriting failure modes that nobody decided how to handle. Make them legible in the plan (tenet XIII). List how it breaks, and for each dependency that can die, decide now whether the system drops a feature or drops the milestone (tenet XIX). What separates an incident from an outage is whether the fallback got designed before anyone needed it.

A dependency: "if the recommender is down, render the page without it", a tier decided in advance, not discovering there's no fallback during the outage.
A migration: the rollback procedure written beside the forward plan, not "we'll figure out rollback if we need it", at the worst possible moment.
A tenant-facing feature: the per-tenant quota named in the plan, not one greedy customer taking down the shared substrate nobody bulkheaded.

Tension: This pulls against simplicity (tenet XXI). Not every risk earns a designed fallback, and an untested degraded path is just a second bug waiting for the worst moment to show up. Plan the tiers you'll actually build and rehearse. For the rest, name the risk and accept it out loud rather than hiding it.

Ask yourself: When the riskiest part of this fails, what is the smallest thing we lose, and did I decide that here, or am I leaving it for the pager?

VIII

Give every artefact an owner and an expiry; title it to reveal

Every issue, flag, and epic has one owner of record and a sunset, and its title encodes the one fact a reader gets wrong without it.

Process is structure for when code structure runs out (tenet XXV). The unowned ticket is the one nobody dares touch during the incident, and the flag with no expiry is the zombie branch that springs back a year later. Give each artefact a single owner so "who owns this?" is never the first question of the outage, and a sunset so the plan doesn't silt up with scaffolding that nobody is ever going to delete (tenet XX). And spend the title - the most-read line of the whole plan - to reveal the load-bearing fact rather than to label (tenet XXII).

An issue: "Bound retry loop in ACP reconnect (unbounded, storms a flaky agent)", title carries the risk, not "fix reconnect", which hides it until the incident.
A flag: an owner and a removal date attached the day it's created, not a permanent branch nobody remembers the purpose of.
A cache or quota: a named owner and a staleness budget in the plan, not a derived copy with no invalidation path back to the truth (tenet XIV).

Tension: This is about precision, not length. A title that encodes the invariant can drift away from it, so don't cram every fact in (migrate-db-with-rollback-and-flag-and-backfill). Reveal the one fact a reader gets wrong and let the linked plan carry the rest (tenet I).

Ask yourself: Does every issue, flag, and epic here name one owner and a sunset, so no one has to ask "who owns this?" mid-incident, and could a reader predict the work and its risk from the title alone?

The through-line

Every move here is the manifesto's one move wearing planning's clothes: push correctness out of the planner's vigilance and into the shape of the plan, bounded unknowns, owned facts, a contract for done, a capped scope, a decision split from its effect, a reversible sequence, named failure modes, and an owner for everything. The person who picks this up should be able to do the right thing while ignorant of 99% of what you held in your head, and not because they remembered to ask. Because the plan already told them, and the wrong path was never something they could express in the first place.

Write the plan for the person who will pick it up cold while a deadline burns, knowing less than you know now. Make the right next step the obvious one, make the irreversible one hard to take by accident, and never make them reconstruct what the plan could have carried for them.