Writing Plans

Writing Plans

Overview

This skill only produces plans — it never runs them. The gap check and ambiguity check planning:executing-plans would otherwise run at hand-off get done here instead, at production time: every step gets an observable check stamped on it before the plan counts as finished, in the same pass-bar vocabulary that skill's QualityGate judges against. Staleness/ drift stays out of scope on purpose — a fact about when execution happens, not how the plan was written — so planning:executing-plans owns that check at hand-off. A clean gap/ambiguity pass here claims nothing about drift.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md (a stated user preference overrides this default).

Process

1. Scope check. One plan, one subsystem — split multi-subsystem specs first.
2. Survey, then structure. Read entry points, tests, and the nearest analogue before inventing file paths; lock which files are touched and what each owns.
3. Right-size the tasks. One testable deliverable per task, 2-5 minute steps: test → fail → implement → pass → commit.
4. Gap check, in-line. Confirm each thing a task consumes was produced by an earlier task — the defect planning:executing-plans screens for; catch it before it ships.
5. Ambiguity check, in-line. Read each step as a stranger would; if they'd guess, resolve it now.
6. Stamp a pass bar per step. The one observable check proving the step is done ("that test now passes", "the endpoint returns 429"). No statable bar means the step isn't finished — go back.
7. Self-review. Scan for placeholders ("TBD", "similar to Task N") and keep names/signatures consistent across tasks.

Output Template

# [Feature Name] Implementation Plan

> Produced by write:writing-plans. Owner for execution routing:
> planning:executing-plans. Steps use checkbox (`- [ ]`) syntax.

**Goal:** [one sentence] **Architecture:** [2-3 sentences]
**Tech Stack:** [key libraries]
---

Per task:

### Task N: [Component]
**Files:** create/modify/test — exact paths.
**Interfaces:** consumes [earlier tasks' signatures] / produces [names
  later tasks rely on].
**Pass bar:** [the observable check from Process step 6]

- [ ] 1: failing test (full code) → 2: confirm it fails → 3: minimal
  implementation (full code) → 4: confirm it passes → 5: commit

No placeholders where real content belongs: no "TBD", no "similar to Task N" without the actual code, no reference to a type or function no earlier task defines.

Dual-Mode

Compact SetGoal example (≤3 subgoals, ≤6 acceptance criteria total):

{
  "goal": "Add rate limiting to the public API",
  "acceptance": ["All public endpoints reject over-limit requests with 429"],
  "subgoals": [{
    "id": "s1",
    "title": "Token-bucket limiter middleware",
    "skills": ["develop:spring-boot-engineer"],
    "acceptance": [
      "Requests over the configured rate return 429",
      "Requests under the rate pass through unchanged"
    ],
    "test": ["./gradlew test --tests RateLimiterTest"],
    "deps": []
  }],
  "max_retries": 2
}

What Claude Does / What You Do

Related

• planning:executing-plans — owns execution routing and the staleness/drift check this skill leaves out on purpose (downstream).
• agents:subagent-driven-development — likely executor once executing-plans routes a sequential/dependent plan.
• completion:verification-before-completion — settles each step's done-verdict against the pass bar stamped here, in solo mode.
• harness:harness — the six-stage engine this skill's harness-mode output feeds directly as a goal-spec.