Execution Plan Writer

ExecPlan: a self-contained living plan

An ExecPlan is a plan document strong enough to be the only context needed to finish the job. Anyone, including a future turn of this conversation with no memory of earlier turns, should be able to read it top to bottom and continue the work. Maintain it as a single document artifact and update it at every stopping point.

Core requirements

• Self-contained. The plan carries every assumption, definition, and piece of background it depends on. Never write "as discussed above" or point at external docs; restate what is needed in the plan itself, in plain language. Define every term of art on first use or do not use it.
• Living. Revise the plan as work proceeds, as surprises appear, and as decisions are made. Each revision must remain self-contained. Add a short note at the bottom describing what changed and why.
• Outcome-anchored. State acceptance as behavior someone can observe ("paste this input and the function returns X"), not as internal attributes ("added a helper class"). Every milestone must produce something demonstrable.
• Novice-guiding. Assume the reader knows nothing about the project beyond what the plan says. Name files, functions, and modules precisely. Resolve ambiguities inside the plan instead of delegating them to the reader.

Structure

Open the plan with a purpose paragraph: what someone can do after this work that they could not do before, and how they will see it working. Then include these sections and keep every one current:

• Progress. A checklist of granular steps with completion marks. Split any partially finished item into done and remaining parts. This section must always reflect the true current state.
• Surprises and Discoveries. Unexpected behavior, bugs, and insights found along the way, each with brief evidence such as an output snippet.
• Decision Log. Every design decision with its rationale, so it is unambiguous why the plan changed.
• Context and Orientation. The current state of the system as if the reader knows nothing: key files by full path, how the pieces fit together, and definitions of any non-obvious terms.
• Plan of Work. Prose describing the sequence of edits and additions, naming each file and location and what to change there.
• Milestones. Narrative, not bureaucracy. For each: scope, what exists at the end that did not before, and the observable acceptance check. Each milestone must be independently verifiable.
• Validation. How to exercise the result and what to observe, with expected outputs so success is distinguishable from failure. Run what can be run in the sandbox and record the actual output; give the user exact steps and expected results for anything only they can run.
• Outcomes and Retrospective. At completion, what was achieved, what remains, and lessons learned, compared against the original purpose.

Working the plan

1. Draft the plan as an artifact before implementing. Research first: read every file or source the plan touches and fold what you learn into Context and Orientation.
2. When executing, proceed milestone by milestone without asking "what next". Resolve ambiguities yourself and record the choice in the Decision Log.
3. Update the artifact at every stopping point: check off progress, log surprises and decisions, and adjust remaining milestones. The plan must never lag behind reality.
4. When requirements carry real unknowns, add an explicit prototyping milestone: a small throwaway experiment run in the sandbox that proves or kills an approach before the full build depends on it. State the criteria for promoting or discarding the prototype.
5. Prefer additive, testable steps that keep the system working between milestones. If a step is risky or destructive, spell out the safe retry or rollback path so steps can be repeated without damage.

Rules

• Write narrative prose in most sections; reserve checklists for Progress.
• Capture evidence. Include concise transcripts or snippets that prove a milestone passed, indented inside the plan.
• Never describe a feature so narrowly that code satisfying the letter of the plan does nothing useful. Over-explain user-visible effects and under-specify incidental implementation detail.
• If the conversation resumes after a gap, reread the plan artifact first and trust it over memory of earlier turns.