[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7C14EB2N1EXZBA6N99SHWBF":3,"skill-same:01M7C14EB2N1EXZBA6N99SHWBF":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7C14EB2N1EXZBA6N99SHWBF","write-plan",null,"Use when you have a spec or requirements for a multi-step task, before touching code","zak-keown\u002Fmoe","zak-keown","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F320717241?v=4","01M7BZFXME0NW6TQX0H7AZM2KS","01M7BZFXN32VR0JN5AATRD53H4",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002F.codex-plugin\u002Fskills\u002Fwrite-plan\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: write-plan\ndescription: Use when you have a spec or requirements for a multi-step task, before touching code\ntriggers: >-\n  Load when you have approved requirements or a design and need to\n  produce a multi-task implementation plan before coding. Do NOT load\n  for: initial exploration or design (use `brainstorming` first),\n  single-file changes, bug fixes, or when a plan document already\n  exists and needs execution (`sdd`).\n---\n\n# Writing Plans\n\n## Overview\n\nWrite comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.\n\nAssume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.\n\n**Announce at start:** \"I'm using the write-plan skill to create the implementation plan.\"\n\n**At this depth:** `write-plan` fires only at the `feature` depth\ndefined in `brainstorming` (patch \u002F change \u002F feature). A `patch` or a\n`change` never produces a plan document — the design lives in chat and\nthe code follows directly.\n\n**Context:** If working in an isolated worktree, it should have been created via the `use-worktrees` skill at execution time.\n\n**Save plans to:** `docs\u002Fmoe\u002Fplans\u002FYYYY-MM-DD-\u003Cfeature-name>.md` — use\n`moe jig plan init \u003Cfeature-name>` to create the file with correct naming and a\nskeleton, then fill in the plan content.\n- (User preferences for plan location override this default)\n\n## Scope Check\n\nIf the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.\n\nWhen you do split into more than one plan, record the ordering in a committed\n`docs\u002Fmoe\u002Fplans\u002F\u003Cproject>-MANIFEST.md` so a fresh session on a partly-finished\nproject can read which plan is runnable next instead of guessing. The\n`sequence-plans` skill covers the manifest format and the `plan-set` CLI.\n\n## File Structure\n\nBefore defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.\n\n- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.\n- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.\n- Files that change together should live together. Split by responsibility, not by technical layer.\n- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.\n\n**Graph-grounded decomposition:** If moedex is available (via the\n`retrieve-context` skill or the `moe:search-moedex` agent), query\n`impact_analysis` on the change target before decomposing tasks. Use the blast\nradius to populate `Files:` blocks from the actual call graph rather than from\nyour reading alone. After writing the plan, run `moe jig plan validate` to\ncheck for uncovered files, missing dependency edges, and wave conflicts. If\nmoedex is unavailable, proceed from your own analysis as before.\n\nThis structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.\n\n## Task Right-Sizing\n\nA task is the smallest unit that carries its own test cycle and is worth a\nfresh reviewer's gate. When drawing task boundaries: fold setup,\nconfiguration, scaffolding, and documentation steps into the task whose\ndeliverable needs them; split only where a reviewer could meaningfully\nreject one task while approving its neighbor. Each task ends with an\nindependently testable deliverable.\n\n## Bite-Sized Task Granularity\n\n**Each step is one action (2-5 minutes):**\n- \"Write the failing test\" - step\n- \"Run it to make sure it fails\" - step\n- \"Implement the minimal code to make the test pass\" - step\n- \"Run the tests and make sure they pass\" - step\n- \"Commit\" - step\n\n## Plan Document Header\n\n**Every plan MUST start with this header:**\n\n```markdown\n# [Feature Name] Implementation Plan\n\n> **For agentic workers:** REQUIRED SUB-SKILL: Use `sdd` (recommended) or `execute-plan` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.\n\n**Goal:** [One sentence describing what this builds]\n\n**Architecture:** [2-3 sentences about approach]\n\n**Tech Stack:** [Key technologies\u002Flibraries]\n\n**Spec:** [path to the spec\u002Fdesign doc this plan implements — the plan\nargues from the spec, so the spec travels with it; executors read both]\n\n## Global Constraints\n\n[The spec's project-wide requirements — version floors, dependency limits,\nnaming and copy rules, platform requirements — one line each, with exact\nvalues copied verbatim from the spec. Every task's requirements implicitly\ninclude this section.]\n\n## Open Decisions\n\n[Questions this plan does NOT answer. A decision is not a work item: what it\nproduces is an answer, not a slice of the build. Delete this section only when\nit is genuinely empty — an empty section and a missing one read differently to\nan executor.]\n\n- **D1 — [short name]** · `research` | `prototype` | `conversation` | `task` · HITL | AFK\n  - **Question:** [the decision, stated precisely]\n  - **Options:** [a] \u002F [b]\n  - **Recommendation:** [a], because [reason]\n  - **Blocked by:** [other decision ids, or —]\n  - **Blocks:** Task 3, Task 7\n  - **Resolution:** [one line, filled in when answered]\n\n## Not Yet Specified\n\n[In-scope questions you can see coming but cannot yet phrase sharply. Write\nthem as loosely as the view allows; this doubles as a signpost for whoever\nreads where the work is headed. Each patch graduates into one or more\ndecisions — or none — once an earlier answer makes it specifiable.]\n\n## Out of Scope\n\n[Work consciously ruled beyond the Goal. One line each, with why. Nothing here\ngraduates: if the Goal is redrawn, that is a fresh plan, not a resumption.]\n\n---\n```\n\n## Task Structure\n\n````markdown\n### Task N: [Component Name]\n\n**depends_on:** [task numbers this task depends on, or []]\n\n**Blocked by:** D1  *(omit this line entirely when no decision blocks the task)*\n\n**Files:**\n- Create: `exact\u002Fpath\u002Fto\u002Ffile.py`\n- Modify: `exact\u002Fpath\u002Fto\u002Fexisting.py:123-145`\n- Test: `tests\u002Fexact\u002Fpath\u002Fto\u002Ftest.py`\n\n**Interfaces:**\n- Consumes: [what this task uses from earlier tasks — exact signatures, or `None`]\n- Produces: [what later tasks rely on — exact function names, parameter\n  and return types. A task's implementer sees only their own task; this\n  block is how they learn the names and types neighboring tasks use. Use\n  `None` when the task has no produced interface.]\n\n- [ ] **Step 1: Write the failing test**\n\n```python\ndef test_specific_behavior():\n    result = function(input)\n    assert result == expected\n```\n\n- [ ] **Step 2: Run test to verify it fails**\n\nRun: `pytest tests\u002Fpath\u002Ftest.py::test_name -v`\nExpected: FAIL with \"function not defined\"\n\n- [ ] **Step 3: Write minimal implementation**\n\n```python\ndef function(input):\n    return expected\n```\n\n- [ ] **Step 4: Run test to verify it passes**\n\nRun: `pytest tests\u002Fpath\u002Ftest.py::test_name -v`\nExpected: PASS\n\n- [ ] **Step 5: Commit**\n\n```bash\ngit add tests\u002Fpath\u002Ftest.py src\u002Fpath\u002Ffile.py\ngit commit -m \"feat: add specific feature\"\n```\n````\n\n## Decisions Are Not Tasks\n\nA task delivers a slice of the Goal. A decision resolves a question, and what\nit produces is an answer. The two need separate ledgers because a plan that\nburies an unmade decision inside a step hands the executor an invented answer\nwith no record that anyone chose it.\n\n**The four kinds of decision.** Each is either **HITL** — worked live with your\nhuman partner, who speaks for themselves — or **AFK**, which you drive alone.\nYou never stand in for the human side of a HITL decision.\n\n- **research** (AFK) — a fact from outside this working tree decides it.\n  Dispatch a subagent to go and find it.\n- **prototype** (HITL) — \"how should it look?\" or \"how should it behave?\" is\n  the real question. Raise the fidelity of the discussion: build the cheapest\n  rough artifact that makes the choice concrete, link it from the decision, and\n  get a reaction to it.\n- **conversation** (HITL) — the default. A judgement only your human partner can\n  make. Put it to them with your recommendation, and wait.\n- **task** (HITL or AFK) — manual work that must happen before a decision can be\n  made at all: provisioning access, moving data so its shape is visible, signing\n  up for a service so its API can be judged. This is the one kind that *does*\n  rather than decides, and it earns its place by unblocking a decision, not by\n  delivering the Goal. Its resolution records what was done plus any facts later\n  decisions depend on.\n\n**Decision or fog?** The test is whether you can state the question precisely\nnow — *not* whether you can answer it now.\n\n- **A decision** when the question is already sharp, even if it is blocked and\n  you cannot act on it yet.\n- **Not Yet Specified** when you cannot yet phrase it that sharply. Do not\n  pre-slice fog into decision-sized pieces: it is coarser than a decision, and\n  one patch may graduate into several, or none.\n\n**The rules:**\n\n- **A gap you can state precisely is a decision, not a missing task.** Inventing\n  an answer and writing it into a step is a placeholder wearing a code block —\n  the same failure the next section names, and harder to spot.\n- **A plan with unresolved decisions is not runnable.** Resolve them with your\n  human partner before dispatching any executor. Filling in **Resolution** is\n  what makes the plan dispatchable; until then, say so when you hand it over.\n- **Work the frontier, not the list.** The frontier is the open decisions whose\n  own **Blocked by** entries are all resolved — the ones answerable now.\n  Resolving one pushes the frontier outward: it unblocks what depended on it,\n  and may graduate a patch of **Not Yet Specified** into a fresh decision.\n- **A decision that turns out to sit past the Goal is not resolved — it is ruled\n  out.** Move it to **Out of Scope** with one line on why, and unblock the tasks\n  that were waiting on it or delete them.\n\n## No Placeholders\n\nEvery step must contain the actual content an engineer needs. These are **plan failures** — never write them:\n- \"TBD\", \"TODO\", \"implement later\", \"fill in details\"\n- \"Add appropriate error handling\" \u002F \"add validation\" \u002F \"handle edge cases\"\n- \"Write tests for the above\" (without actual test code)\n- \"Similar to Task N\" (repeat the code — the engineer may be reading tasks out of order)\n- Steps that describe what to do without showing how (code blocks required for code steps)\n- References to types, functions, or methods not defined in any task\n\n## Self-Review\n\nAfter writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.\n\n**1. Spec coverage:** Skim each section\u002Frequirement in the spec. Can you point to a task that implements it? List any gaps.\n\n**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the \"No Placeholders\" section above. Fix them.\n\n**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.\n\n**4. Decision vs task:** Take every gap you listed in check 1 and sort it — is\nit a missing task, or an unmade decision? A decision belongs in **Open\nDecisions** with the tasks it blocks, never in a step as an invented answer.\nThen check the edges resolve: every `**Blocked by:**` id names a decision that\nexists, and every decision's **Blocks** list names tasks that exist.\n\n**5. Execution metadata:** Validate every task has a `depends_on:` field (or\nomits it, meaning []), a non-empty `Files:` block, an `Interfaces:` block,\nand explicit `Consumes:` and `Produces:` entries. Resolve\n[skills\u002Fsdd\u002Fscripts\u002Ftask-set.mjs](..\u002Fsdd\u002Fscripts\u002Ftask-set.mjs) relative to\nthis loaded document and invoke it as `node \"\u003Cresolved-task-set.mjs>\" check \u003Cplan.md>` to validate\nstructural integrity — cycles, unresolvable deps, missing blocks.\n\nIf you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task — unless the task cannot be written until something is decided, in which case add the decision.\n\n## Presenting the plan\n\nThe plan file on disk is already rung 4 (markdown) of the shared\nnative-rendering ladder in [skills\u002F_shared\u002Fnative-rendering.md](..\u002F_shared\u002Fnative-rendering.md),\nresolved relative to this loaded document.\nEvery executor path ends up reading that file, so no other rung is\nrequired for the workflow to work.\n\nWhen your human partner asks to review the plan visually — a browseable\ntable of tasks, a rendered dependency diagram — walk the ladder from\nthe top:\n\nRung 1 (the Claude Code `Artifact` tool) is not exposed — start at\nrung 2 (the brainstorm browser companion)\nand fall through to rung 3 (local HTML file) or rung 4 (markdown file)\nwhen the sandbox blocks a port bind. Use the shared ladder's sharing\ndefault.\n\n\nNever gate execution on the browseable form; the markdown\nfile is the source of truth.\n\n## Execution Handoff\n\nAfter saving the plan, use ask in the terminal to offer the execution choice:\n\n**\"Plan complete and saved to `docs\u002Fmoe\u002Fplans\u002F\u003Cfilename>.md`. Two execution options:**\n\n**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration\n\n**2. Inline Execution** - Execute tasks in this session using execute-plan, batch execution with checkpoints\n\n**Which approach?\"**\n\n**If Subagent-Driven chosen:**\n- **REQUIRED SUB-SKILL:** Use `sdd`\n- Fresh subagent per task + two-stage review\n\n**If Inline Execution chosen:**\n- **REQUIRED SUB-SKILL:** Use `execute-plan`\n- Batch execution with checkpoints for review\n\n**Either option uses the same two-rung execution ladder.** First use\nworktree-isolated parallel dispatch when the gate holds: tasks' `Files:` blocks\nare pairwise-disjoint, they share no `Consumes:` → `Produces:` edge, and every\nworker has a pairwise-unique linked Git directory branched from one recorded\nbase SHA. If any worktree cannot be created or validated, dispatch the whole\nwave sequentially. There is no unisolated-parallel rung.\n\n`sdd` (Wave grouping, Integrate the wave) and\n`dispatch-agents` (Validate the plan before applying the gate, The\ngate, The divergent-tree rule) define the mechanics. A plan missing `Files:`,\n`Interfaces:`, `Consumes:`, or `Produces:` fails validation before either\nexecution option starts.\n","# Writing Plans\n\n## Overview\n\nWrite comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.\n\nAssume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.\n\n**Announce at start:** \"I'm using the write-plan skill to create the implementation plan.\"\n\n**At this depth:** `write-plan` fires only at the `feature` depth\ndefined in `brainstorming` (patch \u002F change \u002F feature). A `patch` or a\n`change` never produces a plan document — the design lives in chat and\nthe code follows directly.\n\n**Context:** If working in an isolated worktree, it should have been created via the `use-worktrees` skill at execution time.\n\n**Save plans to:** `docs\u002Fmoe\u002Fplans\u002FYYYY-MM-DD-\u003Cfeature-name>.md` — use\n`moe jig plan init \u003Cfeature-name>` to create the file with correct naming and a\nskeleton, then fill in the plan content.\n- (User preferences for plan location override this default)\n\n## Scope Check\n\nIf the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.\n\nWhen you do split into more than one plan, record the ordering in a committed\n`docs\u002Fmoe\u002Fplans\u002F\u003Cproject>-MANIFEST.md` so a fresh session on a partly-finished\nproject can read which plan is runnable next instead of guessing. The\n`sequence-plans` skill covers the manifest format and the `plan-set` CLI.\n\n## File Structure\n\nBefore defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.\n\n- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.\n- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.\n- Files that change together should live together. Split by responsibility, not by technical layer.\n- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.\n\n**Graph-grounded decomposition:** If moedex is available (via the\n`retrieve-context` skill or the `moe:search-moedex` agent), query\n`impact_analysis` on the change target before decomposing tasks. Use the blast\nradius to populate `Files:` blocks from the actual call graph rather than from\nyour reading alone. After writing the plan, run `moe jig plan validate` to\ncheck for uncovered files, missing dependency edges, and wave conflicts. If\nmoedex is unavailable, proceed from your own analysis as before.\n\nThis structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.\n\n## Task Right-Sizing\n\nA task is the smallest unit that carries its own test cycle and is worth a\nfresh reviewer's gate. When drawing task boundaries: fold setup,\nconfiguration, scaffolding, and documentation steps into the task whose\ndeliverable needs them; split only where a reviewer could meaningfully\nreject one task while approving its neighbor. Each task ends with an\nindependently testable deliverable.\n\n## Bite-Sized Task Granularity\n\n**Each step is one action (2-5 minutes):**\n- \"Write the failing test\" - step\n- \"Run it to make sure it fails\" - step\n- \"Implement the minimal code to make the test pass\" - step\n- \"Run the tests and make sure they pass\" - step\n- \"Commit\" - step\n\n## Plan Document Header\n\n**Every plan MUST start with this header:**\n\n```markdown\n# [Feature Name] Implementation Plan\n\n> **For agentic workers:** REQUIRED SUB-SKILL: Use `sdd` (recommended) or `execute-plan` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.\n\n**Goal:** [One sentence describing what this builds]\n\n**Architecture:** [2-3 sentences about approach]\n\n**Tech Stack:** [Key technologies\u002Flibraries]\n\n**Spec:** [path to the spec\u002Fdesign doc this plan implements — the plan\nargues from the spec, so the spec travels with it; executors read both]\n\n## Global Constraints\n\n[The spec's project-wide requirements — version floors, dependency limits,\nnaming and copy rules, platform requirements — one line each, with exact\nvalues copied verbatim from the spec. Every task's requirements implicitly\ninclude this section.]\n\n## Open Decisions\n\n[Questions this plan does NOT answer. A decision is not a work item: what it\nproduces is an answer, not a slice of the build. Delete this section only when\nit is genuinely empty — an empty section and a missing one read differently to\nan executor.]\n\n- **D1 — [short name]** · `research` | `prototype` | `conversation` | `task` · HITL | AFK\n  - **Question:** [the decision, stated precisely]\n  - **Options:** [a] \u002F [b]\n  - **Recommendation:** [a], because [reason]\n  - **Blocked by:** [other decision ids, or —]\n  - **Blocks:** Task 3, Task 7\n  - **Resolution:** [one line, filled in when answered]\n\n## Not Yet Specified\n\n[In-scope questions you can see coming but cannot yet phrase sharply. Write\nthem as loosely as the view allows; this doubles as a signpost for whoever\nreads where the work is headed. Each patch graduates into one or more\ndecisions — or none — once an earlier answer makes it specifiable.]\n\n## Out of Scope\n\n[Work consciously ruled beyond the Goal. One line each, with why. Nothing here\ngraduates: if the Goal is redrawn, that is a fresh plan, not a resumption.]\n\n---\n```\n\n## Task Structure\n\n````markdown\n### Task N: [Component Name]\n\n**depends_on:** [task numbers this task depends on, or []]\n\n**Blocked by:** D1  *(omit this line entirely when no decision blocks the task)*\n\n**Files:**\n- Create: `exact\u002Fpath\u002Fto\u002Ffile.py`\n- Modify: `exact\u002Fpath\u002Fto\u002Fexisting.py:123-145`\n- Test: `tests\u002Fexact\u002Fpath\u002Fto\u002Ftest.py`\n\n**Interfaces:**\n- Consumes: [what this task uses from earlier tasks — exact signatures, or `None`]\n- Produces: [what later tasks rely on — exact function names, parameter\n  and return types. A task's implementer sees only their own task; this\n  block is how they learn the names and types neighboring tasks use. Use\n  `None` when the task has no produced interface.]\n\n- [ ] **Step 1: Write the failing test**\n\n```python\ndef test_specific_behavior():\n    result = function(input)\n    assert result == expected\n```\n\n- [ ] **Step 2: Run test to verify it fails**\n\nRun: `pytest tests\u002Fpath\u002Ftest.py::test_name -v`\nExpected: FAIL with \"function not defined\"\n\n- [ ] **Step 3: Write minimal implementation**\n\n```python\ndef function(input):\n    return expected\n```\n\n- [ ] **Step 4: Run test to verify it passes**\n\nRun: `pytest tests\u002Fpath\u002Ftest.py::test_name -v`\nExpected: PASS\n\n- [ ] **Step 5: Commit**\n\n```bash\ngit add tests\u002Fpath\u002Ftest.py src\u002Fpath\u002Ffile.py\ngit commit -m \"feat: add specific feature\"\n```\n````\n\n## Decisions Are Not Tasks\n\nA task delivers a slice of the Goal. A decision resolves a question, and what\nit produces is an answer. The two need separate ledgers because a plan that\nburies an unmade decision inside a step hands the executor an invented answer\nwith no record that anyone chose it.\n\n**The four kinds of decision.** Each is either **HITL** — worked live with your\nhuman partner, who speaks for themselves — or **AFK**, which you drive alone.\nYou never stand in for the human side of a HITL decision.\n\n- **research** (AFK) — a fact from outside this working tree decides it.\n  Dispatch a subagent to go and find it.\n- **prototype** (HITL) — \"how should it look?\" or \"how should it behave?\" is\n  the real question. Raise the fidelity of the discussion: build the cheapest\n  rough artifact that makes the choice concrete, link it from the decision, and\n  get a reaction to it.\n- **conversation** (HITL) — the default. A judgement only your human partner can\n  make. Put it to them with your recommendation, and wait.\n- **task** (HITL or AFK) — manual work that must happen before a decision can be\n  made at all: provisioning access, moving data so its shape is visible, signing\n  up for a service so its API can be judged. This is the one kind that *does*\n  rather than decides, and it earns its place by unblocking a decision, not by\n  delivering the Goal. Its resolution records what was done plus any facts later\n  decisions depend on.\n\n**Decision or fog?** The test is whether you can state the question precisely\nnow — *not* whether you can answer it now.\n\n- **A decision** when the question is already sharp, even if it is blocked and\n  you cannot act on it yet.\n- **Not Yet Specified** when you cannot yet phrase it that sharply. Do not\n  pre-slice fog into decision-sized pieces: it is coarser than a decision, and\n  one patch may graduate into several, or none.\n\n**The rules:**\n\n- **A gap you can state precisely is a decision, not a missing task.** Inventing\n  an answer and writing it into a step is a placeholder wearing a code block —\n  the same failure the next section names, and harder to spot.\n- **A plan with unresolved decisions is not runnable.** Resolve them with your\n  human partner before dispatching any executor. Filling in **Resolution** is\n  what makes the plan dispatchable; until then, say so when you hand it over.\n- **Work the frontier, not the list.** The frontier is the open decisions whose\n  own **Blocked by** entries are all resolved — the ones answerable now.\n  Resolving one pushes the frontier outward: it unblocks what depended on it,\n  and may graduate a patch of **Not Yet Specified** into a fresh decision.\n- **A decision that turns out to sit past the Goal is not resolved — it is ruled\n  out.** Move it to **Out of Scope** with one line on why, and unblock the tasks\n  that were waiting on it or delete them.\n\n## No Placeholders\n\nEvery step must contain the actual content an engineer needs. These are **plan failures** — never write them:\n- \"TBD\", \"TODO\", \"implement later\", \"fill in details\"\n- \"Add appropriate error handling\" \u002F \"add validation\" \u002F \"handle edge cases\"\n- \"Write tests for the above\" (without actual test code)\n- \"Similar to Task N\" (repeat the code — the engineer may be reading tasks out of order)\n- Steps that describe what to do without showing how (code blocks required for code steps)\n- References to types, functions, or methods not defined in any task\n\n## Self-Review\n\nAfter writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.\n\n**1. Spec coverage:** Skim each section\u002Frequirement in the spec. Can you point to a task that implements it? List any gaps.\n\n**2. Placeholder scan:** Search your plan for red flags — any of the patterns from the \"No Placeholders\" section above. Fix them.\n\n**3. Type consistency:** Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called `clearLayers()` in Task 3 but `clearFullLayers()` in Task 7 is a bug.\n\n**4. Decision vs task:** Take every gap you listed in check 1 and sort it — is\nit a missing task, or an unmade decision? A decision belongs in **Open\nDecisions** with the tasks it blocks, never in a step as an invented answer.\nThen check the edges resolve: every `**Blocked by:**` id names a decision that\nexists, and every decision's **Blocks** list names tasks that exist.\n\n**5. Execution metadata:** Validate every task has a `depends_on:` field (or\nomits it, meaning []), a non-empty `Files:` block, an `Interfaces:` block,\nand explicit `Consumes:` and `Produces:` entries. Resolve\n[skills\u002Fsdd\u002Fscripts\u002Ftask-set.mjs](..\u002Fsdd\u002Fscripts\u002Ftask-set.mjs) relative to\nthis loaded document and invoke it as `node \"\u003Cresolved-task-set.mjs>\" check \u003Cplan.md>` to validate\nstructural integrity — cycles, unresolvable deps, missing blocks.\n\nIf you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task — unless the task cannot be written until something is decided, in which case add the decision.\n\n## Presenting the plan\n\nThe plan file on disk is already rung 4 (markdown) of the shared\nnative-rendering ladder in [skills\u002F_shared\u002Fnative-rendering.md](..\u002F_shared\u002Fnative-rendering.md),\nresolved relative to this loaded document.\nEvery executor path ends up reading that file, so no other rung is\nrequired for the workflow to work.\n\nWhen your human partner asks to review the plan visually — a browseable\ntable of tasks, a rendered dependency diagram — walk the ladder from\nthe top:\n\nRung 1 (the Claude Code `Artifact` tool) is not exposed — start at\nrung 2 (the brainstorm browser companion)\nand fall through to rung 3 (local HTML file) or rung 4 (markdown file)\nwhen the sandbox blocks a port bind. Use the shared ladder's sharing\ndefault.\n\n\nNever gate execution on the browseable form; the markdown\nfile is the source of truth.\n\n## Execution Handoff\n\nAfter saving the plan, use ask in the terminal to offer the execution choice:\n\n**\"Plan complete and saved to `docs\u002Fmoe\u002Fplans\u002F\u003Cfilename>.md`. Two execution options:**\n\n**1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration\n\n**2. Inline Execution** - Execute tasks in this session using execute-plan, batch execution with checkpoints\n\n**Which approach?\"**\n\n**If Subagent-Driven chosen:**\n- **REQUIRED SUB-SKILL:** Use `sdd`\n- Fresh subagent per task + two-stage review\n\n**If Inline Execution chosen:**\n- **REQUIRED SUB-SKILL:** Use `execute-plan`\n- Batch execution with checkpoints for review\n\n**Either option uses the same two-rung execution ladder.** First use\nworktree-isolated parallel dispatch when the gate holds: tasks' `Files:` blocks\nare pairwise-disjoint, they share no `Consumes:` → `Produces:` edge, and every\nworker has a pairwise-unique linked Git directory branched from one recorded\nbase SHA. If any worktree cannot be created or validated, dispatch the whole\nwave sequentially. There is no unisolated-parallel rung.\n\n`sdd` (Wave grouping, Integrate the wave) and\n`dispatch-agents` (Validate the plan before applying the gate, The\ngate, The divergent-tree rule) define the mechanics. A plan missing `Files:`,\n`Interfaces:`, `Consumes:`, or `Produces:` fails validation before either\nexecution option starts.\n",{"name":5,"triggers":23,"description":7},"Load when you have approved requirements or a design and need to produce a multi-task implementation plan before coding. Do NOT load for: initial exploration or design (use `brainstorming` first), single-file changes, bug fixes, or when a plan document already exists and needs execution (`sdd`).","main","728894f3f85fbd4e788f015ddfd72bb6155d5dd5","plugins\u002Fmoe\u002F.codex-plugin\u002Fskills\u002Fwrite-plan",1,"https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe","https:\u002F\u002Fgithub.com\u002Fzak-keown","2026-09-05 06:29:06",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add zak-keown\u002Fmoe --skill write-plan",{"tool":37,"command":38},"bunx","bunx skills add zak-keown\u002Fmoe --skill write-plan",{"tool":40,"command":41},"pnpm","pnpm dlx skills add zak-keown\u002Fmoe --skill write-plan","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002F.codex-plugin\u002Fskills\u002Fwrite-plan\u002FSKILL.md",true,[45],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"plan-document-reviewer-prompt.md","REFERENCE","参考文档",1978,"https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002F.codex-plugin\u002Fskills\u002Fwrite-plan\u002Fplan-document-reviewer-prompt.md",[52,59,64,71,78,85],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M7C1Z5362Y8NVRZ69HWP0ZD0","write-skill","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-skill\u002FSKILL.md",[],[],{"skillNo":60,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":18},"01M7C1YZ9966WK9R6ZRPCGWF3G","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-plan\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":18},"01M7C1YMR4SJD7BPBBPXZCVGVH","write-clearly","Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-clearly\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":18},"01M7C1YH9805YSM0N20VQAVSXF","windows-vm","Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM.","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwindows-vm\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":18},"01M7C1YD87SCNEJ2C9B8HFR2NQ","verify-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating MRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fverify-completion\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":18},"01M7C1YARDEHT0TJ9BRG30ZCF4","using-moe","Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fusing-moe\u002FSKILL.md",[],[]]