diff --git a/docs/doperpowers/specs/2026-07-03-execplan-track-design.md b/docs/doperpowers/specs/2026-07-03-execplan-track-design.md index 204614b4e4..ddfdc0c5cc 100644 --- a/docs/doperpowers/specs/2026-07-03-execplan-track-design.md +++ b/docs/doperpowers/specs/2026-07-03-execplan-track-design.md @@ -5,15 +5,16 @@ ## The track ``` -grill (Matt Pocock's grilling, vendored; domain-modeling's interview moves absorbed) +brainstorming's grill (Matt Pocock's grilling, vendored there; domain-modeling's interview moves absorbed) + → brainstorming's track router (human partner explicitly chooses autonomous) → one ExecPlan (skills/execspec/references/PLANS.md followed TO THE LETTER) → autonomous execution in a worktree (living updates, milestones, frequent commits) → exit gate: final whole-branch review → merge ``` -One new skill, `skills/execplan/SKILL.md`, carries the whole track. No hooks into existing skills — the track is an alternative *entry*, not a modification of the default pipeline. +One skill, `skills/execplan/SKILL.md`, carries the authoring/execution/exit contract. Entry is routed from doperpowers:brainstorming: its grill is this track's Step 1, and its track-choice step hands off here on the human partner's explicit choice (revised 2026-07-05; originally the track was a standalone alternative entry with no hooks into existing skills — see Decision Log). -- **Grill step**: MP's grilling text vendored verbatim (10 lines, attributed), plus three interview moves kept from domain-modeling (sharpen fuzzy terms, stress-test with concrete scenarios, cross-reference claims with code). All output lands in the ExecPlan: definitions inline, decisions in its Decision Log. No CONTEXT.md, no ADRs. +- **Grill step**: MP's grilling text vendored verbatim (10 lines, attributed) in doperpowers:brainstorming's clarification step, plus three interview moves kept from domain-modeling (sharpen fuzzy terms, stress-test with concrete scenarios, cross-reference claims with code) — one vendor point serving both tracks. All output lands in the ExecPlan: definitions inline, decisions in its Decision Log. No CONTEXT.md, no ADRs. - **Authoring step**: the SAME vendored PLANS.md that execspec adapts is here consumed unmodified — including the clauses the execspec adapter supersedes for the controlled track (Progress, milestones, novice-grade self-containment, autonomous ambiguity resolution). One vendor point, two consumption modes. ExecPlans live at `docs/doperpowers/execplans/YYYY-MM-DD-.md`. - **Execution step**: PLANS.md's implementing contract as written — no next-step prompts, living sections current at every stopping point, frequent commits — in an isolated worktree. Daemon-compatible by construction (the ExecPlan is exactly what a spawn prompt can carry and survives context death); v1 notes the fit, mandates nothing. - **Exit gate**: exactly one — the final whole-branch review before merge; finishing's retrospective step writes into the ExecPlan's own `Outcomes & Retrospective` section (the ExecPlan is this track's spec-equivalent). @@ -22,13 +23,14 @@ One new skill, `skills/execplan/SKILL.md`, carries the whole track. No hooks int ## What does NOT change -The execspec pipeline and its four hooks; the vendored PLANS.md (still one copy, still never edited); brainstorming (no cross-pointer — each track triggers on its own description). +The execspec pipeline and its four hooks; the vendored PLANS.md (still one copy, still never edited). (Original version also listed "brainstorming — no cross-pointer"; reversed 2026-07-05, see Decision Log: brainstorming now carries the grill and the track router.) ## Verification - `ls skills/execplan/` → `SKILL.md` - `grep -c "execspec/references/PLANS.md" skills/execplan/SKILL.md` → at least 1 (shared vendor point, no second copy) -- `grep -c "one at a time" skills/execplan/SKILL.md` → 1 (vendored grill text present verbatim) +- `grep -c "one at a time" skills/brainstorming/SKILL.md` → at least 1 (vendored grill text present verbatim; moved from execplan 2026-07-05) +- `grep -c "execplan" skills/brainstorming/SKILL.md` → at least 1 (track router present) - Behavioral, on first real use: a session pointed at a well-scoped task produces one file under `docs/doperpowers/execplans/` containing PLANS.md's living sections (`Progress`, `Surprises & Discoveries`, `Decision Log`, `Outcomes & Retrospective`) and executes it to a reviewed merge without asking "should I proceed?" mid-flight. ## Decision Log @@ -49,6 +51,10 @@ The execspec pipeline and its four hooks; the vendored PLANS.md (still one copy, Rationale: One vendor point cannot fork; the difference between tracks is consumption mode, not source text. The clauses execspec "rejected" were track-mismatches, not defects — this track is where they run as written. Date/Author: 2026-07-03 +- Decision: Vendor the grill (and the three interview moves) in doperpowers:brainstorming, and route into this track from a thin router there on the human partner's explicit choice — reversing "no cross-pointer; each track triggers on its own description". + Rationale: Two days of real state showed the standalone entry never fires mechanically: brainstorming auto-triggers at every task start and captures every entry, this track's description never triggered on its own (its one real use — ida-solution T13, 2026-07-03 — was deliberately invoked, and `docs/doperpowers/execplans/` never appeared in this repo), and issue-register had independently vendored an adapted grill for its clarify step, confirming the interview protocol belongs at clarification time. One vendor point for the interview text; execplan keeps authoring + execution + exit gate. Router guard: routing is never silent — a delegation phrase ("just handle it") is not a track choice; the human partner names the track. Rejected alternative: folding this track into execspec with routing guidance in a memory note — loses the document-as-machinery mode (Progress/Concrete Steps/self-containment that daemons need across context death) and puts routing where it never mechanically triggers. + Date/Author: 2026-07-05 (human partner proposed the brainstorming router; assessed and adopted) + - Decision: This feature itself ships with a short spec and no implementation plan. Rationale: Single-file task — a plan would exceed the work (writing-plans is for multi-step tasks). The spec exists because the conversation produced real rejected alternatives that must survive (the fold-in challenge earlier today demonstrated the cost of undocumented rationale); it is deliberately short. Date/Author: 2026-07-03 (human partner questioned the ceremony; right-sized together) @@ -61,6 +67,9 @@ The execspec pipeline and its four hooks; the vendored PLANS.md (still one copy, - Observation: ExecPlan's most dangerous clause ("do not prompt the user; resolve ambiguities autonomously") becomes safe when the human gate is front-loaded rather than removed — the grill exhausts the ambiguity space while the human is present. Evidence: The validity gaps identified in the original doperpowers-vs-ExecPlan analysis (no elicitation protocol, no term-definition method, undifferentiated decision lifetimes) map one-to-one onto grilling, domain-modeling's glossary moves, and the ADR three-condition test. +- Observation: The single-vendor-point decision drifted within hours of shipping — commit 1562e6e ("vendor PLANS.md in execplan") duplicated PLANS.md into `skills/execplan/references/` with no recorded rationale, silently breaking this spec's own verification grep. Reverted 2026-07-05. + Evidence: `git show 1562e6e --stat` (150-line copy added same evening); `grep -c "execspec/references/PLANS.md" skills/execplan/SKILL.md` → 0 until the revert. + ## Outcomes & Retrospective **2026-07-03, at finish.** Shipped as designed, same conversation: `skills/execplan/SKILL.md` (grill vendored verbatim with attribution, three domain-modeling moves absorbed, authoring bound to the shared vendored PLANS.md to the letter, worktree execution, single exit gate). All structural verification passed on the first run (`ls`, both greps = 1). Right-sizing held: no plan was written and none was missed — the skill file was a single transcription-grade artifact. @@ -71,3 +80,4 @@ The methodology portfolio is now two-track: controlled (execspec pipeline, gates - 2026-07-03: Initial version — terminal artifact of the grill-shaped design conversation (ExecPlan-only resolution, exit-gate default, right-sizing decision). - 2026-07-03: Outcomes & Retrospective written at finish; structural verification results recorded. +- 2026-07-05: Grill re-homed to doperpowers:brainstorming (single vendor point, both tracks) and brainstorming gained a thin track router — the human partner's explicit choice hands off to execplan; reverses the no-cross-pointer decision (see Decision Log entry of this date). Duplicate PLANS.md copy from 1562e6e reverted, restoring the shared vendor point. Body sections (The track, What does NOT change, Verification) updated to match. diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index eb3c2e3416..d40afb09c0 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -23,20 +23,23 @@ You MUST create a task for each of these items and complete them in order: 1. **Explore project context** — check files, docs, recent commits 2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below. -3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria -4. **Propose 2-3 approaches** — with trade-offs and your recommendation -5. **Present design** — in sections scaled to their complexity, get user approval after each section -6. **Write design doc** — in living-spec shape per doperpowers:execspec (purpose-first opening, behavior-phrased acceptance, living tail with the Decision Log seeded from step 4's alternatives); save to `docs/doperpowers/specs/YYYY-MM-DD--design.md` and commit -7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) -8. **User reviews written spec** — ask user to review the spec file before proceeding -9. **Transition to implementation** — invoke writing-plans skill to create implementation plan +3. **Grill** — clarifying questions one at a time per The Grill below; understand purpose/constraints/success criteria +4. **Choose the track with your human partner** — controlled (continue below, the default) or autonomous (hand off to doperpowers:execplan); see Choosing the Track below +5. **Propose 2-3 approaches** — with trade-offs and your recommendation +6. **Present design** — in sections scaled to their complexity, get user approval after each section +7. **Write design doc** — in living-spec shape per doperpowers:execspec (purpose-first opening, behavior-phrased acceptance, living tail with the Decision Log seeded from step 5's alternatives); save to `docs/doperpowers/specs/YYYY-MM-DD--design.md` and commit +8. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) +9. **User reviews written spec** — ask user to review the spec file before proceeding +10. **Transition to implementation** — invoke writing-plans skill to create implementation plan ## Process Flow ```dot digraph brainstorming { "Explore project context" [shape=box]; - "Ask clarifying questions" [shape=box]; + "Grill (clarifying questions)" [shape=box]; + "Human partner chooses autonomous track?" [shape=diamond]; + "Invoke execplan skill" [shape=doublecircle]; "Propose 2-3 approaches" [shape=box]; "Present design sections" [shape=box]; "User approves design?" [shape=diamond]; @@ -45,8 +48,10 @@ digraph brainstorming { "User reviews spec?" [shape=diamond]; "Invoke writing-plans skill" [shape=doublecircle]; - "Explore project context" -> "Ask clarifying questions"; - "Ask clarifying questions" -> "Propose 2-3 approaches"; + "Explore project context" -> "Grill (clarifying questions)"; + "Grill (clarifying questions)" -> "Human partner chooses autonomous track?"; + "Human partner chooses autonomous track?" -> "Invoke execplan skill" [label="yes, explicitly"]; + "Human partner chooses autonomous track?" -> "Propose 2-3 approaches" [label="no (default)"]; "Propose 2-3 approaches" -> "Present design sections"; "Present design sections" -> "User approves design?"; "User approves design?" -> "Present design sections" [label="no, revise"]; @@ -58,7 +63,7 @@ digraph brainstorming { } ``` -**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans. +**The terminal state is invoking writing-plans** — or doperpowers:execplan when your human partner explicitly chose the autonomous track. Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skills you invoke after brainstorming are writing-plans (controlled track) and execplan (autonomous track, on your human partner's explicit choice). ## The Process @@ -67,11 +72,34 @@ digraph brainstorming { - Check out the current project state first (files, docs, recent commits) - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first. - If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle. -- For appropriately-scoped projects, ask questions one at a time to refine the idea +- For appropriately-scoped projects, run the grill below to refine the idea - Prefer multiple choice questions when possible, but open-ended is fine too -- Only one question per message - if a topic needs more exploration, break it into multiple questions - Focus on understanding: purpose, constraints, success criteria +**The Grill** — vendored verbatim from Matt Pocock's `grilling` skill; this is the clarification protocol: + +> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. +> +> Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. +> +> If a question can be answered by exploring the codebase, explore the codebase instead. + +Three moves to use throughout (kept from his `domain-modeling` skill; its artifacts are not used here): + +- **Sharpen fuzzy terms** — propose a precise canonical term: "You're saying 'account' — do you mean the Customer or the User? Those are different things." +- **Stress-test with concrete scenarios** — invent scenarios that probe edge cases and force precision about the boundaries between concepts. +- **Cross-reference with code** — when your human partner states how something works, check whether the code agrees; surface contradictions. + +Triage the grilling: grill what is fuzzy or important; don't grind an already-clear request to death. + +**Choosing the Track (after the grill):** + +Two tracks leave this skill. The controlled track — the rest of this skill: approaches → design → spec → doperpowers:writing-plans — is the default. The autonomous track hands off to doperpowers:execplan, which authors one self-contained ExecPlan and executes it with no mid-flight human gates. + +- Offer the autonomous track only when the work is delegable and the grill has exhausted the ambiguity space. Test during the grill: if taste questions keep hitting "we can't know until we try," stay controlled — feasibility unknowns are fine, they become prototyping milestones in the ExecPlan. +- Routing is your human partner's explicit choice — never route silently, and never treat "just handle it" as a track choice; name the track and get a yes. Their explicit choice to go autonomous is the approval the HARD-GATE requires; doperpowers:execplan's contract governs from there. +- No offer made, or no explicit yes → continue this skill (controlled). + **Exploring approaches:** - Propose 2-3 different approaches with trade-offs diff --git a/skills/execplan/SKILL.md b/skills/execplan/SKILL.md index 3d35071887..9dad3517cd 100644 --- a/skills/execplan/SKILL.md +++ b/skills/execplan/SKILL.md @@ -11,32 +11,20 @@ This repo has two development tracks. The controlled pipeline (doperpowers:brain ## Which track? -- **This track**: the work is delegable and a grill can resolve every open question up front. Fits long-running work and durable background daemons. -- **Controlled track**: taste-heavy, novel, or high-stakes work where design judgment keeps arising mid-flight → doperpowers:brainstorming. +Routing lives in doperpowers:brainstorming's track choice (its grill is this track's Step 1) — you normally arrive here with the grill done and your human partner having explicitly chosen this track. -Test during the grill: if you keep hitting "we can't know until we try" on *taste* questions, stop and route to the controlled track. (Feasibility unknowns are fine here — they become prototyping milestones in the ExecPlan.) +- **This track**: the work is delegable and the grill can resolve every open question up front. Fits long-running work and durable background daemons. +- **Controlled track**: taste-heavy, novel, or high-stakes work where design judgment keeps arising mid-flight → doperpowers:brainstorming. ## Step 1 — Grill -Vendored verbatim from Matt Pocock's `grilling` skill: - -> Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. -> -> Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. -> -> If a question can be answered by exploring the codebase, explore the codebase instead. - -Three moves to use throughout (kept from his `domain-modeling` skill; its artifacts are not used here): - -- **Sharpen fuzzy terms** — propose a precise canonical term: "You're saying 'account' — do you mean the Customer or the User? Those are different things." -- **Stress-test with concrete scenarios** — invent scenarios that probe edge cases and force precision about the boundaries between concepts. -- **Cross-reference with code** — when your human partner states how something works, check whether the code agrees; surface contradictions. +The grill and its three interview moves (sharpen fuzzy terms, stress-test with concrete scenarios, cross-reference with code) are vendored verbatim in doperpowers:brainstorming's clarification step — one vendor point, shared by both tracks. You normally arrive here with the grill already done. Entering this track directly? Run doperpowers:brainstorming's grill first — never author an ExecPlan from an un-grilled conversation. Everything the grill resolves lands in the ExecPlan: term definitions inline where used, decisions (with the rejected alternatives and why) in its Decision Log. No CONTEXT.md, no ADRs — the ExecPlan is this track's only artifact. ## Step 2 — Author the ExecPlan -Read [../execplan/references/PLANS.md](../execplan/references/PLANS.md) in full and follow it **to the letter** — including the sections the execspec adapter supersedes for the controlled track (Progress with timestamped checkboxes, narrative milestones, Concrete Steps, novice-grade self-containment). That is track separation, not contradiction: over there, machinery replaces those sections; here, the document IS the machinery. +Read [../execspec/references/PLANS.md](../execspec/references/PLANS.md) in full and follow it **to the letter** — including the sections the execspec adapter supersedes for the controlled track (Progress with timestamped checkboxes, narrative milestones, Concrete Steps, novice-grade self-containment). That is track separation, not contradiction: over there, machinery replaces those sections; here, the document IS the machinery. Save to `docs/doperpowers/execplans/YYYY-MM-DD-.md` (omit the triple-backtick envelope per PLANS.md's file rule). The bar: a fresh session with no conversation history — or a daemon spawned with nothing but this file — can implement it end-to-end and see it working. diff --git a/skills/execplan/references/PLANS.md b/skills/execplan/references/PLANS.md deleted file mode 100644 index c38d4cbd29..0000000000 --- a/skills/execplan/references/PLANS.md +++ /dev/null @@ -1,150 +0,0 @@ -# Codex Execution Plans (ExecPlans): - -This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context. - -## How to use ExecPlans and PLANS.md - -When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research. - -When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve ambiguities autonomously, and commit frequently. - -When discussing an executable specification (ExecPlan), record decisions in a log in the spec for posterity; it should be unambiguously clear why any change to the specification was made. ExecPlans are living documents, and it should always be possible to restart from _only_ the ExecPlan and no other work. - -When researching a design with challenging requirements or significant unknowns, use milestones to implement proof of concepts, "toy implementations", etc., that allow validating whether the user's proposal is feasible. Read the source code of libraries by finding or acquiring them, research deeply, and include prototypes to guide a fuller implementation. - -## Requirements - -NON-NEGOTIABLE REQUIREMENTS: - -* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed. -* Every ExecPlan is a living document. Contributors are required to revise it as progress is made, as discoveries occur, and as design decisions are finalized. Each revision must remain fully self-contained. -* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo. -* Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition". -* Every ExecPlan must define every term of art in plain language or do not use it. - -Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe. - -The agent executing your plan can list files, read files, search, run the project, and run tests. It does not know any prior context and cannot infer what you meant from earlier milestones. Repeat any assumption you rely on. Do not point to external blogs or docs; if knowledge is required, embed it in the plan itself in your own words. If an ExecPlan builds upon a prior ExecPlan and that file is checked in, incorporate it by reference. If it is not, you must include all relevant context from that plan. - -## Formatting - -Format and envelope are simple and strict. Each ExecPlan must be one single fenced code block labeled as `md` that begins and ends with triple backticks. Do not nest additional triple-backtick code fences inside; when you need to show commands, transcripts, diffs, or code, present them as indented blocks within that single fence. Use indentation for clarity rather than code fences inside an ExecPlan to avoid prematurely closing the ExecPlan's code fence. Use two newlines after every heading, use # and ## and so on, and correct syntax for ordered and unordered lists. - -When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks. - -Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Narrative sections must remain prose-first. - -## Guidelines - -Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself. - -Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details. - -Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior). - -Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable. - -Be idempotent and safe. Write the steps so they can be run multiple times without causing damage or drift. If a step can fail halfway, include how to retry or adapt. If a migration or destructive operation is necessary, spell out backups or safe fallbacks. Prefer additive, testable changes that can be validated as you go. - -Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results. - -Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs. - -## Milestones - -Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, and the acceptance you expect to observe. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Never abbreviate a milestone merely for the sake of brevity, do not leave out details that could be crucial to a future implementation. - -Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan. - -## Living plans and design decisions - -* ExecPlans are living documents. As you make key design decisions, update the plan to record both the decision and the thinking behind it. Record all decisions in the `Decision Log` section. -* ExecPlans must contain and maintain a `Progress` section, a `Surprises & Discoveries` section, a `Decision Log`, and an `Outcomes & Retrospective` section. These are not optional. -* When you discover optimizer behavior, performance tradeoffs, unexpected bugs, or inverse/unapply semantics that shaped your approach, capture those observations in the `Surprises & Discoveries` section with short evidence snippets (test output is ideal). -* If you change course mid-implementation, document why in the `Decision Log` and reflect the implications in `Progress`. Plans are guides for the next contributor as much as checklists for you. -* At completion of a major task or the full plan, write an `Outcomes & Retrospective` entry summarizing what was achieved, what remains, and lessons learned. - -# Prototyping milestones and parallel implementations - -It is acceptable—-and often encouraged—-to include explicit prototyping milestones when they de-risk a larger change. Examples: adding a low-level operator to a dependency to validate feasibility, or exploring two composition orders while measuring optimizer effects. Keep prototypes additive and testable. Clearly label the scope as “prototyping”; describe how to run and observe results; and state the criteria for promoting or discarding the prototype. - -Prefer additive code changes followed by subtractions that keep tests passing. Parallel implementations (e.g., keeping an adapter alongside an older path during migration) are fine when they reduce risk or enable tests to continue passing during a large migration. Describe how to validate both paths and how to retire one safely with tests. When working with multiple new libraries or feature areas, consider creating spikes that evaluate the feasibility of these features _independently_ of one another, proving that the external library performs as expected and implements the features we need in isolation. - -## Skeleton of a Good ExecPlan - - # - - 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 PLANS.md file is checked into the repo, reference the path to that file here from the repository root and note that this document must be maintained in accordance with PLANS.md. - - ## 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. - - - [x] (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 - - State the exact commands to run and where to run them (working directory). When a command generates output, show a short expected transcript so the reader can compare. This section must be updated as work proceeds. - - ## Validation and Acceptance - - Describe how to start or exercise the system and what to observe. Phrase acceptance as behavior, with specific inputs and outputs. If tests are involved, say "run and expect passed; the new test fails before the change and passes after>". - - ## Idempotence and Recovery - - If steps can be repeated safely, say so. If a step is risky, provide a safe retry or rollback path. Keep the environment clean after completion. - - ## Artifacts and Notes - - Include the most important transcripts, diffs, or snippets as indented examples. Keep them concise and focused on what proves success. - - ## Interfaces and Dependencies - - Be prescriptive. Name the libraries, modules, and services to use and why. Specify the types, traits/interfaces, and function signatures that must exist at the end of the milestone. Prefer stable names and paths such as `crate::module::function` or `package.submodule.Interface`. E.g.: - - In crates/foo/planner.rs, define: - - pub trait Planner { - fn plan(&self, observed: &Observed) -> Vec; - } - -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.