17 Write plans that preserve intent

A plan can be detailed enough to keep an agent busy and still be missing the reason for the work. “Add a downloader, validate the file, update the catalog” names activities. It does not say what must remain true if validation fails, which version the consumer should see during replacement, or who may decide that a different resource is an acceptable substitute. Those omissions will become implementation decisions, often without anybody noticing that a decision was made.

The handoff from discovery to implementation should preserve the information that constrains those choices. It should also discard conversational material that no longer helps. A transcript may contain abandoned suggestions, tentative interpretations, repeated explanations, and an eventual agreement. Handing all of it to an implementer can obscure which statements now govern the work.

For a substantial change, a useful plan is a small current account of the outcome, the decisions that shape it, and the evidence needed to accept it. Supporting investigations remain available by reference. The plan does not need to impersonate the entire repository's documentation.

Begin with a consequence the implementer must preserve

Our illustrative application already has a usable resource. We want to acquire a replacement, check it, and make it available through the same consumer interface. The central consequence is that a preparation failure before publication must not destroy the working version. This remains an educational example, not a description of Pumas Library's architecture.

A compact handoff might read:

Outcome: A consumer can open the requested replacement after publication. Until publication succeeds, new consumer requests continue to resolve to the previously active version.

Scope: Local acquisition, integrity checking, publication, and status reporting for one supported resource format. Automatic substitution and runtime installation are excluded from this change.

Binding decisions: Candidates are prepared outside the active location. Publication changes the active reference only after the selected checks succeed. The publication owner decides whether the transition committed; the progress display cannot make that decision.

Unresolved assumption: The supported storage environment must provide the required reference-switch behavior. Investigate this before choosing the publication implementation.

Next slice: Establish a consumer-level replacement test and implement the smallest publication path that can satisfy it. Keep acquisition behind a controlled fixture until the publication assumption is resolved.

Acceptance: Open the old version while the candidate is held before publication. Reject an invalid candidate and open the old version again. Publish a valid candidate and open the requested replacement. Report the environment and revision exercised.

This artifact connects work to behavior. It also changes the order a plausible implementation might otherwise take. Building a sophisticated downloader first would postpone the unresolved assumption that could invalidate the design. The next slice instead investigates the risky publication boundary with a deliberately uninteresting source of bytes.

The scope statement is equally consequential. An agent that discovers a missing runtime may report it and propose additional work. It cannot infer permission to install something merely because installation would help the test pass. A plan needs to distinguish an obstacle inside the agreed work from a new product commitment.

Preserve reasons selectively

Not every decision needs an essay. The reason for staging separately could be one sentence: the current version must remain usable when preparation fails. That sentence helps a later implementer recognize an apparently simpler in-place rewrite as a change in behavior, rather than a harmless refactor.

Record a rejected option when its attraction makes it likely to return, or when a new fact could make it preferable. “In-place replacement was rejected because readers could observe partial content” is useful. A catalogue of every library considered during research usually is not. If a lengthy investigation remains relevant, link its conclusion and the conditions under which it should be revisited.

Puma's inspected planning standard makes a similar proportional distinction. It permits a clear bounded repair to proceed with an inline write set and acceptance path, while requiring a written plan for material sequencing, contract, migration, coordination, rollout, risk, or acceptance complexity. The rule is an inspectable policy, not evidence that every application of it succeeds. Planning, pinned revision.

For a spelling correction in a known status label, the plan might be a sentence. For changing what that label means across a service, API, and interface, the contract must survive several handoffs. The distinction follows the decisions that need preservation, not the number of edited files.

Make stale understanding detectable

A plan becomes dangerous when it describes a world implementation has already disproved. Suppose inspection reveals that an existing reader holds the active path open throughout its work. The statement about “new consumer requests” remains useful, but the plan now needs to distinguish new readers from existing ones. The implementer should surface that distinction before quietly making old readers follow the replacement too.

One current decision owner prevents competing summaries from becoming competing authorities. A task brief can quote the binding rule and link back to it; it should not become an independently editable copy. When the rule changes, affected task owners need the change and its implications, not merely a notification that the document was updated.

There is an opposite failure: keeping the plan impeccable while useful work stalls. A discovered alternative can be documented without reopening settled choices that it does not affect. Investigation can also end with the conclusion that no change is needed. A plan is valuable when it helps choose and finish work, including deciding not to start it.

Try the handoff without the conversation

Choose a real change and give another person, or a fresh agent session, only its compact plan and the referenced repository. Ask for the intended consumer behavior, the first implementation slice, and one condition that requires a new decision. Do not grade whether the answer copies your wording. Check whether it preserves the consequential distinctions.

If the recipient can produce a plausible implementation that violates your intention while satisfying every sentence, add the missing invariant or example. If they spend their effort reconciling duplicated guidance, remove a competing copy. The observable outcome is a handoff that permits independent progress while making the next consequential misunderstanding visible.