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:

# [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

- `<exact path>` — <responsibility and reason for change>

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.

### Task N: <name>

**Outcome:** <observable result>

**Files/Modules:**
- Create: `<exact path>` — <responsibility>
- Modify: `<exact path>` — <responsibility>
- Test: `<exact path>` — <behavior covered>

**Interfaces:**
- Consumes: `<existing exact function or type signatures, command, event, or none>`
- Produces: `<new exact function or type signatures, command, event, or none>`

**Public Seams:**
- <confirmed callable boundary used to observe behavior>

**Behavior Slices:**
- Scenario: <caller-facing situation>
  Input: <concrete input or trigger>
  Observable result: <what the confirmed seam exposes>
  Independent expectation source: <literal, worked example, or requirement>
  Verification: tested (risk: <branching | boundary | transformation | state-transition | protocol-compat>) | verified (gate: <bound execution point>; reason_no_test: <why no dedicated test>)

**Implementation Design:**
- <exact symbols and responsibilities to add or change>
- <data flow, state transition, algorithm, and boundary interactions>
- <error behavior, compatibility, migration, and documentation impact>
- <pseudocode or small critical snippet when prose leaves material ambiguity>

**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: <one tested behavior slice>

- Test: `<exact test path>` — `<exact test name and observable assertion>`
- Expected RED: `<exact focused command>` fails because `<missing behavior, not syntax/setup failure>`
- Minimal implementation: `<exact files and symbols; smallest behavior needed for this slice>`
- Expected GREEN: `<exact focused command>` passes with `<observable result>`
- Learning checkpoint: <what to inspect before specifying or implementing the next slice>

#### Slice 2: <next tested behavior slice informed by Slice 1>

- Test: `<exact test path>` — `<exact test name and observable assertion>`
- Expected RED: `<exact focused command>` fails because `<missing behavior>`
- Minimal implementation: `<exact files and symbols; smallest behavior needed for this slice>`
- Expected GREEN: `<exact focused command>` passes with `<observable result>`
- Learning checkpoint: <what may refine later slices without changing approved scope>

#### Verified slice: <behavior slice with mode verified>

- Gate: `<bound execution point that observes this acceptance point>`
- Reason: <why no dedicated test>

**Focused Verification:** `<exact focused command covering the completed task>`

**Acceptance Checklist:**
- [ ] <task-specific observable requirement>
- [ ] <compatibility, error, migration, or documentation requirement when applicable>

**Dependencies:** <task IDs and exact produced interfaces consumed, or none>

**Commit Intent:** `<conventional commit subject>`

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.

{
  "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:

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:

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.