|
| 1 | +# Codex Execution Plans (ExecPlans) |
| 2 | + |
| 3 | +This file defines how to write and maintain an ExecPlan: a self-contained, living specification that a novice can follow to deliver observable, working behavior in this repository. |
| 4 | + |
| 5 | +## When to Use an ExecPlan |
| 6 | +- Required for multi-step or multi-file work, new features, refactors, or tasks expected to take more than about an hour. |
| 7 | +- Optional for trivial fixes (typos, small docs), but if you skip it for a substantial task, state the reason in your response. |
| 8 | + |
| 9 | +## How to Use This File |
| 10 | +- Authoring: read this file end to end before drafting; start from the skeleton; embed all context (paths, commands, definitions) so no external docs are needed. |
| 11 | +- Implementing: move directly to the next milestone without asking for next steps; keep the living sections current at every stopping point. |
| 12 | +- Discussing: record decisions and rationale inside the plan so work can be resumed later using only the ExecPlan. |
| 13 | + |
| 14 | +## Non-Negotiable Requirements |
| 15 | +- Self-contained and beginner-friendly: define every term; include needed repo knowledge; avoid assuming prior plans or external links. |
| 16 | +- Living document: revise Progress, Surprises & Discoveries, Decision Log, and Outcomes & Retrospective as work proceeds while keeping the plan self-contained. |
| 17 | +- Outcome-focused: describe what the user can do after the change and how to see it working; the plan must lead to demonstrably working behavior, not just code edits. |
| 18 | +- Explicit acceptance: state behaviors, commands, and observable outputs that prove success. |
| 19 | + |
| 20 | +## Formatting Rules |
| 21 | +- Default envelope is a single fenced code block labeled `md`; do not nest other triple backticks inside—indent commands, transcripts, and diffs instead. |
| 22 | +- If the file contains only the ExecPlan, omit the enclosing code fence. |
| 23 | +- Use blank lines after headings; prefer prose over lists. Checklists are permitted only in the Progress section (and are mandatory there). |
| 24 | + |
| 25 | +## Guidelines |
| 26 | +- Define jargon immediately and tie it to concrete files or commands in this repo. |
| 27 | +- Anchor on outcomes: acceptance should be phrased as observable behavior; for internal changes, show tests or scenarios that demonstrate the effect. |
| 28 | +- Specify repository context explicitly: full paths, functions, modules, working directory for commands, and environment assumptions. |
| 29 | +- Be idempotent and safe: describe retries or rollbacks for risky steps; prefer additive, testable changes. |
| 30 | +- Validation is required: state exact test commands and expected outputs; include concise evidence (logs, transcripts, diffs) as indented examples. |
| 31 | + |
| 32 | +## Milestones |
| 33 | +- Tell a story (goal → work → result → proof) for each milestone; keep them narrative rather than bureaucratic. |
| 34 | +- Each milestone must be independently verifiable and incrementally advance the overall goal. |
| 35 | +- Milestones are distinct from Progress: milestones explain the plan; Progress tracks real-time execution. |
| 36 | + |
| 37 | +## Living Sections (must be present and maintained) |
| 38 | +- Progress: checkbox list with timestamps; every pause should update what is done and what remains. |
| 39 | +- Surprises & Discoveries: unexpected behaviors, performance notes, or bugs with brief evidence. |
| 40 | +- Decision Log: each decision with rationale and date/author. |
| 41 | +- Outcomes & Retrospective: what was achieved, remaining gaps, and lessons learned. |
| 42 | + |
| 43 | +## Prototyping and Parallel Paths |
| 44 | +- Prototypes are encouraged to de-risk changes; keep them additive, clearly labeled, and validated. |
| 45 | +- Parallel implementations are acceptable when reducing risk; describe how to validate each path and how to retire one safely. |
| 46 | + |
| 47 | +## ExecPlan Skeleton |
| 48 | + |
| 49 | +```md |
| 50 | +# <Short, action-oriented description> |
| 51 | + |
| 52 | +This ExecPlan is a living document. The sections Progress, Surprises & Discoveries, Decision Log, and Outcomes & Retrospective must stay up to date as work proceeds. |
| 53 | + |
| 54 | +If PLANS.md is present in the repo, maintain this document in accordance with it and link back to it by path. |
| 55 | + |
| 56 | +## Purpose / Big Picture |
| 57 | +Explain the user-visible behavior gained after this change and how to observe it. |
| 58 | + |
| 59 | +## Progress |
| 60 | +- [x] (2025-10-01 13:00Z) Example completed step. |
| 61 | +- [ ] Example incomplete step. |
| 62 | +- [ ] Example partially completed step (completed: X; remaining: Y). |
| 63 | + |
| 64 | +## Surprises & Discoveries |
| 65 | +- Observation: … |
| 66 | + Evidence: … |
| 67 | + |
| 68 | +## Decision Log |
| 69 | +- Decision: … |
| 70 | + Rationale: … |
| 71 | + Date/Author: … |
| 72 | + |
| 73 | +## Outcomes & Retrospective |
| 74 | +Summarize outcomes, gaps, and lessons learned; compare to the original purpose. |
| 75 | + |
| 76 | +## Context and Orientation |
| 77 | +Describe the current state relevant to this task as if the reader knows nothing. Name key files and modules by full path; define any non-obvious terms. |
| 78 | + |
| 79 | +## Plan of Work |
| 80 | +Prose description of the sequence of edits and additions. For each edit, name the file and location and what to change. |
| 81 | + |
| 82 | +## Concrete Steps |
| 83 | +Exact commands to run (with working directory). Include short expected outputs for comparison. |
| 84 | + |
| 85 | +## Validation and Acceptance |
| 86 | +Behavioral acceptance criteria plus test commands and expected results. |
| 87 | + |
| 88 | +## Idempotence and Recovery |
| 89 | +How to retry or roll back safely; ensure steps can be rerun without harm. |
| 90 | + |
| 91 | +## Artifacts and Notes |
| 92 | +Concise transcripts, diffs, or snippets as indented examples. |
| 93 | + |
| 94 | +## Interfaces and Dependencies |
| 95 | +Prescribe libraries, modules, and function signatures that must exist at the end. Use stable names and paths. |
| 96 | +``` |
| 97 | + |
| 98 | +## Revising a Plan |
| 99 | +- When the scope shifts, rewrite affected sections so the document remains coherent and self-contained. |
| 100 | +- After significant edits, add a short note at the end explaining what changed and why. |
0 commit comments