# Writing Plans > Use when you have a spec or requirements for a multi-step task, before touching code. Creates detailed, seam-first implementation plans with vertical TDD steps for superharness workflows. - Skill: `mrlyk/writing-plans` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mrlyk/writing-plans` - Raw SKILL.md: https://api.skillmd.com/api/skills/mrlyk/writing-plans/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: mrlyk (https://skillmd.com/u/mrlyk) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mrlyk/writing-plans --- # Writing Plans ## Overview Write a detailed implementation plan for an implementer with no prior codebase context. Fix the architecture, file responsibilities, cross-task interfaces, public seams, behavior slices, implementation decisions, vertical TDD steps, and acceptance evidence before implementation starts. Keep discovery inside the TDD loop. Provide exact signatures, commands, expected behavior, pseudocode, and small critical snippets when they remove ambiguity. Do not prewrite the complete final test suite or implementation. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." Run after batch-grill-me and to-prd have produced an approved PRD. Save the plan to `.superharness/tasks/{MM}-{DD}-{name}/plan.md`; the task directory should already exist and be in `phase: "plan"`. ## Read Before Planning Read every applicable source below before defining tasks. Each source has one distinct role; when sources disagree, the conflict goes to the user, never into the plan. ### Always Read - **PRD and contract** — `prd.md`, `contract.md` in the task directory. - Role: define approved scope and acceptance. Nothing in the plan may exceed or contradict them. - **Project specifications** — the specs under `.superharness/spec/` relevant to the change. - Role: project-wide conventions and hard constraints the plan must copy into Global Constraints when applicable. - **Learnings** — `.superharness/spec/learnings/index.md` plus any topic page relevant to the change. - Role: recorded learnings constrain the plan the same way specs do. - **Codebase, test conventions, and Git state** — existing code, test layout, and the current branch baseline. - Role: the codebase defines current behavior and public seams. Trace the current call path and identify the public types, functions, commands, or UI boundaries the change must preserve or extend. Resolve concrete facts from the repository instead of leaving discovery to the implementer. ### Read When Present - **Wiki archive** — every document in the task's `wiki/` directory. - Role: business-domain sources captured during the interview; they supply business intent and history. - Skip silently when the directory is absent or empty. Do not refresh external knowledge sources at this stage. - **Design bundles** — every approved handoff bundle in the task's `design/` directory. Read each bundle's `meta.yaml` and `index.html`, and inspect referenced local assets when they affect implementation. - Role: approved bundles are the source of truth for design details. Carry implementation-relevant platform, mode, tokens, components, states, actions, assets, editable blocks, baseline, and changes into the plan's `File Structure`, `Behavior Slices`, `Implementation Design`, and `Acceptance Checklist`. Use exact bundle paths as expectation sources. Turn states, actions, and visible feedback into observable behavior slices. - Skip silently when `design/` is absent or empty. Do not refresh external sources or modify the approved bundle at this stage. ### On Conflict Surface inconsistencies between a bundle's `meta.yaml` and `index.html`, or between a bundle and the PRD or contract, to the user. Stop before finalizing the plan. ## Scope and File Structure Split independent subsystems into separate plans when each can produce useful, testable software on its own. Within one plan, add a `## File Structure` section after Global Constraints. List every file expected to be created, modified, or tested, with its single responsibility and why it belongs in that task. Follow existing codebase organization. State any intentional file split, shared abstraction, generated artifact, migration, or documentation change. Do not include speculative refactors. Each task must produce one coherent observable outcome, fit one fresh implementer turn, and end in exactly one implementation commit. Avoid tiny bookkeeping tasks and broad tasks whose behavior or diff cannot be reviewed completely in the final whole-task review. ## Plan the Seams Map files and modules to the public boundaries callers use. Each task needs one or more confirmed seams and enough behavior slices to cover its acceptance criteria. For Full work, confirm **Public Seams** in the approved plan. For Lite work, start from `contract.md` **Test Seams** and ask the user only when a needed seam remains unclear. ## Choose Each Slice's Verification Mode Every behavior slice declares how it is verified. `tested` slices enter the red-green loop; `verified` slices are covered by an existing gate and get no dedicated test. Testing effort must land on critical paths and complex logic, not on every checkable sentence. A slice is `tested` only when all three hold: 1. Its expected result has a stable, independent expectation source (literal, worked example, or requirement). 2. It has meaningful error space: branching, boundaries, data transformation, state transitions, or protocol compatibility. 3. Its failure is observable at a confirmed public seam. When the criteria hold but long-term test maintenance clearly outweighs regression risk, prefer `verified` — this cost judgment is a tiebreaker, never a reason to skip a risk-bearing behavior. A `tested` slice declares a `risk` tag naming its error space. A `verified` slice declares `reason_no_test` and binds `gate` to a real execution point that observes that exact acceptance point: a focused or integration verification command, an E2E case id, or a `contract.md` Acceptance Checklist item. A gate that cannot observe the acceptance point is invalid — typecheck cannot verify copy. A manual procedure must land as a `contract.md` Acceptance Checklist item so the reviewer and finishing actually check it. Static copy, fixed rendering, pure passthrough, and shapes the type system already guarantees default to `verified`. Copy that is itself a contract stays `tested`: legal, price, or payment wording, accessibility names, i18n key mappings, state-dependent copy, and prompt or skill text whose content is executable behavior. ## Plan Document Header Every plan starts with: ```markdown # [Feature Name] Implementation Plan **Goal:** [One sentence describing what this builds] **Architecture:** [2-3 sentences about the approach] **Tech Stack:** [Key technologies/libraries] ## Global Constraints [Project-wide hard constraints copied from the specification, or "None".] ## File Structure - `` — ``` ## Task Schema Use three distinct planning levels: a task is the implementation and commit unit; a behavior slice is one observable scenario within a task; a tested behavior slice's RED → GREEN cycle may be called a tracer bullet. A tracer bullet is never a CLI, JSON, state, or scheduler field. Each task uses this schema. Keep paths, symbols, commands, and expected results exact. Order vertical TDD steps by behavior slice; do not create a reviewer checkpoint per task. ````markdown ### Task N: **Outcome:** **Files/Modules:** - Create: `` — - Modify: `` — - Test: `` — **Interfaces:** - Consumes: `` - Produces: `` **Public Seams:** - **Behavior Slices:** - Scenario: Input: Observable result: Independent expectation source: Verification: tested (risk: ) | verified (gate: ; reason_no_test: ) **Implementation Design:** - - - - **Vertical TDD Steps:** Write TDD steps for `tested` slices only. A `verified` slice appears once with its gate and reason instead of TDD steps. #### Slice 1: - Test: `` — `` - Expected RED: `` fails because `` - Minimal implementation: `` - Expected GREEN: `` passes with `` - Learning checkpoint: #### Slice 2: - Test: `` — `` - Expected RED: `` fails because `` - Minimal implementation: `` - Expected GREEN: `` passes with `` - Learning checkpoint: #### Verified slice: - Gate: `` - Reason: **Focused Verification:** `` **Acceptance Checklist:** - [ ] - [ ] **Dependencies:** **Commit Intent:** `` ```` ## Detail Quality Bar Use enough slices to cover the task's acceptance behavior. Every slice states its scenario, input, observable result, independent expectation source, and verification mode. Each `tested` slice's TDD steps identify the exact test location, intended assertion, RED reason, minimal implementation boundary, and GREEN evidence; each `verified` slice names its bound gate and reason. Make the plan executable without rediscovering settled design: - Name exact files, modules, symbols, exact function or type signatures, commands, state changes, and error behavior. - Define cross-task `Consumes` and `Produces` contracts consistently; later tasks must use the same names and types introduced earlier. - Include pseudocode or small code snippets for fragile data shapes, protocol formats, or algorithms when exactness matters. - Use literal expected values or requirement references; never derive expected results from the proposed implementation. - Cover compatibility, migrations, documentation, observability, and cleanup only when the requirement or current architecture needs them. - Replace vague instructions such as “add validation,” “handle errors,” “write tests,” or “similar to Task N” with concrete behavior and locations. - Stop and ask the user when an unresolved choice would change public behavior, architecture, scope, or irreversible data handling. Keep the planned loop vertical. Do not batch all tests before all implementation, require complete code in every step, prescribe 2–5 minute transcription microsteps, or move refactoring into RED/GREEN. Exactly one `Commit Intent` belongs to each task; the execution controller owns status writes and commits. ## Update Task Artifacts During the plan phase, the controller initializes `tasks`, `seams`, and `behavior_slices` atomically by writing a temporary file in the task directory and renaming it over `task.json`. Preserve existing lifecycle fields. Preserve each task's `id`, `name`, and `status`; add `seams` and `behavior_slices` — including each slice's `verification` declaration — as the plan facts used during implementation. For a Full plan, every task must also persist two DAG facts before the atomic replacement: `depends_on` and `focused_verification`. Interface contracts and planned files stay in plan.md prose (Interfaces, Files/Modules) as dispatch context — the CLI does not enforce them. Run `validateTaskDag(tasks)` before writing the temporary file. Reject duplicate ids, unknown dependencies, dependency cycles, empty `focused_verification`, and malformed slice `verification` declarations; do not replace `task.json` when validation fails. Lite plans retain their serial task schema. ```json { "sprint": { "current": 0, "total": 2 }, "tasks": [ { "id": 1, "name": "Task name", "status": "pending", "depends_on": [], "focused_verification": ["npx vitest run tests/unit/example.test.ts"], "seams": ["public callable boundary"], "behavior_slices": [ { "scenario": "caller-facing situation", "input": "concrete trigger", "observable_result": "visible behavior", "expectation_source": "requirement AC-1", "verification": { "mode": "tested", "risk": "state-transition" } }, { "scenario": "static confirmation copy", "input": "successful save", "observable_result": "success message rendered", "expectation_source": "prd.md UI copy", "verification": { "mode": "verified", "gate": "e2e case save-flow", "reason_no_test": "static copy, no branching or state" } } ] } ] } ``` Update `contract.md` when the plan refines the Done Definition. Commit the plan and task artifacts. After the user approves `plan.md`, transition the lifecycle before implementation: ```bash superharness task transition {task-id} implement ``` After transition to `implement`, direct `task.json` edits are forbidden. All status, result, commit, and sprint progress updates must use `superharness task item`. ## E2E Gate Check Before self-review, invoke `superharness:e2e-gen` for its gate check. The gate check only decides — it generates nothing at this stage. Record the outcome: `e2e:gate-passed` (browser-verifiable UI behavior found; the Execution Handoff will offer generation) or `e2e:skipped` with its reason. ## Self-Review Before handoff, verify: - Every PRD requirement maps to a task and an explicit verification mode; every risk-bearing behavior maps to a `tested` slice. - Every `verified` slice's gate is a real execution point that observes its acceptance point, and manual procedures appear in `contract.md`'s Acceptance Checklist. - Every test seam is confirmed and each expected result has an independent source. - The File Structure accounts for every planned create, modify, test, migration, and documentation path. - Cross-task interfaces use consistent names, types, and ownership. - Every task includes actionable implementation design and ordered vertical TDD steps. - RED reasons represent missing behavior; GREEN commands and focused verification are exact. - Acceptance checklists cover behavior, errors, compatibility, migration, and documentation where applicable. - No placeholder language leaves settled design or repository facts for the implementer to rediscover. - Task sizes fit one implementation commit and the final reviewer can cover the declared task and integration diff. - `task.json` preserves `id`, `name`, and `status` while persisting `seams` and `behavior_slices` with their `verification` declarations. - The e2e-gen gate check ran and its outcome (`e2e:gate-passed` or `e2e:skipped`) is recorded in the trace. ## Execution Handoff Tell the user the plan path and E2E gate status. Determine the current gate status from the last `e2e:gate-passed` or `e2e:skipped` event in the task trace. Read `.superharness/config.yaml`, then present the applicable choices at this existing handoff: 1. **Run Plan adversarial review** — when `review.mode` is `on-demand`, invoke `superharness:adversarial-review` with the task-id and target `plan`, then return to this handoff. 2. **Generate E2E cases** — only when the current gate status is `e2e:gate-passed` and `e2e-cases.yaml` does not exist. Invoke the `superharness:e2e-gen` generation stage, ensure each browser-required acceptance criterion has an E2E case, then return to this handoff. 3. **Approve and use `superharness:subagent-driven-development`** — approve the plan and use Full execution. 4. **Approve and use `superharness:executing-plans`** — approve the plan and use Inline execution. When `review.mode` is `off`, omit the adversarial option. Omit the E2E option when the gate did not pass or `e2e-cases.yaml` already exists. Adversarial review and E2E generation do not approve the plan. When the user picks an approval choice while the current gate status is `e2e:gate-passed` but `e2e-cases.yaml` does not exist, the user has declined generation. Record the decline first, then transition: ```bash superharness task e2e {task} skipped --detail "用户在 Execution Handoff 选择不生成 E2E 用例" ``` There is no explicit skip menu item — not choosing generation and approving is the decline, same as the adversarial option. Only after either approval choice, transition with `superharness task transition {task-id} implement` and start the selected execution skill.