Best attempt based on screencaps & asking Gemini to fill in the text for the last four sections.
# Skeleton of a Good ExecPlan
```md
# <Short, action-oriented description>
```
This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds.
If you follow the guidance above, a single, stateless agent – or a human novice – can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED.
When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections, and you must write a note at the bottom of the plan describing the change and the reason why. ExecPlans must describe not just the what but the why for almost everything.
## Purpose / Big Picture
Explain in a few sentences what someone gains after this change and how they can see it working. State the user-visible behavior you will enable.
## Progress
Use a list with checkboxes to summarize granular steps. Every stopping point must be documented here, even if it requires splitting a partially completed task into two (“done” vs. “remaining”). This section must always reflect the actual current state of the work.
- ` (2025-10-01 13:00Z) Example completed step.`
- ` Example incomplete step.`
- ` Example partially completed step (completed: X; remaining: Y).`
Use timestamps to measure rates of progress.
## Surprises & Discoveries
Document unexpected behaviors, bugs, optimizations, or insights discovered during implementation. Provide concise evidence.
- Observation: …
- Evidence: …
## Decision Log
Record every decision made while working on the plan in the format:
- Decision: …
- Rationale: …
- Date/Author: …
## Outcomes & Retrospective
Summarize outcomes, gaps, and lessons learned at major milestones or at completion. Compare the result against the original purpose.
## Context and Orientation
Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans.
## Plan of Work
Describe, in prose, the sequence of edits and additions. For each edit, name the file and location (function, module) and what to insert or change. Keep it concrete and minimal.
## Concrete Steps
Provide a numbered or bulleted list of the exact, literal commands to run or actions to take. This section is the script for the human to follow. A novice should be able to execute these steps by copying and pasting without deep understanding. Do not explain the “why” here; that belongs in the “Plan of Work”.
- ` Step 1: Run this command: `…
- ` Step 2: Edit file X and paste the following content: `…
- ` Step 3: Run this other command: `…
## Validation and Acceptance
Define the specific, observable criteria that will prove the “Purpose” has been achieved. List the steps to verify the outcome. This is the quality assurance check for the plan.
- How to verify:
1. Run the test suite: `…`
2. Observe that the output now includes `…`
3. Manually check that the user interface at `…` now shows the new behavior.
## Idempotence and Recovery
Describe how to handle failures and re-runs. State how to get the system back to a known-good state if a step fails. Explain if and how the “Concrete Steps” can be safely run more than once.
## Artifacts and Notes
Provide links to any supporting documents, mockups, logs, or other artifacts produced or consumed during this work. This is a catch-all for any information that is necessary for context but does not fit elsewhere.
- [Link to design document](…)
- [Link to related ticket](…)
- Example output log: `…`