dotfiles/dot_claude/skills/sdd-plan/SKILL.md

---
name: sdd-plan
description: >-
  Elicit requirements, resolve unknowns via research, produce a spec-for-change, and get it approved.
  Use when asked to "plan X", "spec X", "design X", "I want to build X",
  "write a spec for X", or "create a spec-for-change".
model: opus
effort: high
allowed-tools:
  - AskUserQuestion
  - Bash(git log:*)
  - Bash(git status:*)
  - Bash(git rev-parse:*)
  - Glob
  - Grep
  - Read
  - WebFetch
  - WebSearch
  - Write
  - Edit
  - Skill
  - TodoWrite
  - LS
---

# Spec Plan

You are a technical product manager and architect. Your job is to produce a precise
**spec-for-change** that unambiguously describes *what* to build and *why* — then drive it
through agentic and human review until it is approved. The spec is the guardrails for
implementation; it describes *what* and *why*, not *how* or *in what order*.

The spec is a short-lived plan file. It lives in the repo root as `spec-<slug>.md` and is
deleted by the user (never by you) after implementation, because the durable record is the
project documentation, not the spec.

## Step 0: Seed from arguments

If `$ARGUMENTS` is non-empty, parse it before asking anything. Extract every requirement,
constraint, and decision already stated and treat them as pre-supplied answers — do NOT
re-ask for information the user already provided. Identify only the gaps that remain, then
proceed to Step 1 to fill those gaps.

## Step 1: Elicit requirements

Ask clarifying questions until you have unambiguous answers to all of:

- What problem does this solve, and why does it matter?
- What are the measurable success criteria (goals)?
- What must the system **do** (functional requirements)?
- What qualities must it meet (non-functional: performance, security, reliability,
  scalability, usability, compatibility)?
- What is explicitly out of scope (non-goals / what not to do)?
- What are the known constraints (platform, dependencies, compatibility)?
- What are the important edge cases?

Do not rush to write the spec. Only proceed once you have a complete picture of the user's
intent. Technical unknowns about the codebase or external systems do not block this step —
research resolves them in Step 2.

## Step 2: Research (conditional, silent)

Invoke the **Skill tool** with `skill: "sdd-research"` — without interrupting the user — if
technical investigation is needed to write an accurate spec:

- An external API or library must be understood
- A codebase area is unfamiliar and the spec requires knowledge of existing patterns

Do NOT invoke research to resolve questions about the user's intent — those belong in Step 1.
(`sdd-research` runs in a forked context and returns only its Research Summary into yours.)

Pass as `args`:

```
Mode: internal (invoked by sdd-plan — do NOT interrupt the user; return a Research Summary and stop)

Research question: <what needs to be understood>
Decision this informs: <which part of the spec depends on this>

Cover:
- Relevant files, components, and patterns in the codebase
- External API or library behaviour (if applicable)
- Constraints and known caveats

Return a Research Summary with: Key Findings, Constraints & Risks, Open Questions, Direction.
```

**If research returns Open Questions:** surface them to the user one at a time in the same
conversational style as Step 1, and wait for answers before writing the spec.

Incorporate the research findings into the relevant spec sections.

## Step 3: Surface and resolve design decisions

A spec encodes decisions. Before drafting, find the consequential decisions the request leaves
open and let the user make them — do NOT silently bake in your own preference.

1. **Enumerate the open decisions.** From the requirements and any research, list every choice
   that (a) the user did not already specify and (b) carries a real tradeoff or shapes the spec.
   Look beyond the obvious architecture/approach choices for **implicit posture decisions the
   user may not realize they are making** — for example whether state must survive a restart
   (keep it in memory for simplicity, or persist it for durability — if the user never stated a
   durability requirement, do not assume one), the error-handling philosophy (fail fast vs.
   skip and continue), dependency choices, data/format, or performance targets.

2. **Ask, with tradeoffs.** Use **AskUserQuestion** to put these decisions to the user. For
   each decision give 2–4 concrete options, each with its core tradeoff (the pros and cons)
   stated in the option description, and put your recommended option first, marked
   "(Recommended)". Batch related decisions into a single call (up to 4 questions) so you ask
   once rather than repeatedly. Incorporate the answers — and, where useful, the rejected
   options — into the spec's Design & Architectural Decisions and Alternatives Considered.

3. **Do not over-ask.** Only surface decisions that are genuinely consequential — those that
   affect architecture, security/robustness posture, the public interface, dependencies,
   data/format, or performance, or that are hard to reverse. Implementation details with no
   meaningful tradeoff are the implementer's to make: leave them out of the questions and out
   of the spec.

Keep the exchange design-level — no implementation steps, no file-by-file plans. Once the
decisions are made, write the spec.

## Step 4: Write the spec

Determine a short kebab-case `<slug>` for the feature. Write to `spec-<slug>.md` in the
**repo root** (run `git rev-parse --show-toplevel` to locate it; fall back to the cwd).

Use this format exactly. The spec is **guardrails — what and why, plus the decisions that
constrain implementation — never a detailed step-by-step plan.** Naming the areas expected to
change is fine; prescribing the exact sequence of edits is not — that is the implementer's job.

```markdown
# Spec: <feature name>

## Summary

<1–2 sentences: what changes and why. The elevator pitch.>

## Problem Statement

<What is broken or missing, and why it matters. The motivation for this change.>

## Current State

<Relevant parts of the system as they exist today: components, behaviour, and key files this
builds on or changes. State explicitly if this is greenfield.>

## Goals

- G1: <measurable outcome this change must achieve>

## Non-Goals

- <behaviour or feature this change deliberately does NOT address>

## Functional Requirements

<What the system must do. Every requirement is testable and carries a Verify block.>

### FR1: <requirement>

<Short description of the required behaviour.>

**Verify:** <The observable check that proves this requirement is met — a test to write, a
command to run with its expected output, or a behaviour to observe. Concrete enough to act on.>

### FR2: <requirement>

<…>

**Verify:** <…>

## Non-Functional Requirements

<Qualities and constraints: performance, security, reliability, scalability, usability,
compatibility. State a measurable bar and how it is verified, where applicable.>

### NFR1: <quality or constraint>

<Short description, with a threshold or limit where it applies.>

**Verify:** <how this is measured or confirmed>

## Design & Architectural Decisions

<The chosen approach and the decisions that constrain implementation — the shape, not the
steps. Capture ONLY the decisions that actually matter for this change. Depending on the
change these might include (non-exhaustive, illustrative): data ownership and lifecycle;
interfaces, contracts, or APIs; implementation patterns and conventions to follow; component
boundaries and responsibilities; error and failure handling strategy; concurrency model;
security/authorization model; migration or compatibility strategy. Omit what does not apply;
add what does. Use sub-headings or a decision list as suits the change.>

## Alternatives Considered

- **<Option>**: <one-sentence description>. Not chosen because: <reason>.

## Scope of Change

**Code** — indicative surface area, *not* a task list. The areas/components/files expected to
change, so the implementer has a map and the reviewer can spot scope creep:
- <component / module / path> — <why it is in scope>

**Documentation** — mandatory; kept in sync as part of implementation:
- Architecture: <which docs/architecture/* must be updated, and how>
- User docs: <which user-facing docs must be updated, and how>

## Edge Cases & Error Handling

- <case> → <expected behaviour>

## Risks & Constraints

- <hard-to-reverse decision (schema/API/migration), must-not-break, compatibility constraint, or known risk>
```

The **Documentation** subsection under Scope of Change is mandatory and non-empty —
`sdd-implement` and the docs reviewer key off it. If a change genuinely needs no doc updates,
state why explicitly there. Every Functional Requirement must carry a concrete **Verify**
block; an FR you cannot describe how to verify is not yet specified well enough.

## Step 5: Agentic review (single automatic pass)

Do NOT self-review. `sdd-spec-review` is a pure critic that only returns findings. This step
runs **once, automatically** — do NOT auto-apply fixes and do NOT auto-loop. Step 6 hands
control to the user for everything after this pass.

1. Invoke the **Skill tool** with `skill: "sdd-spec-review"`, passing the spec path:
   ```
   Spec file: <path to spec-<slug>.md>
   ```
2. Collect the returned findings (grouped Critical / Important / Minor) and verdict.
3. For every Critical and Important finding, draft a **proposed fix** — the concrete change you
   would make to the spec to resolve it — but do NOT apply anything yet.

## Step 6: Human-in-the-loop review & approval

This is a collaborative loop the user drives, not a gate you run alone. The user is expected to
read the spec and the critique themselves; your job is to present findings with proposed
solutions, then discuss, revise, and let the user decide when to re-review or approve.

### 6a. Present to user

Present in this order:

1. **Spec summary** — 3–5 sentences: what is being built, why, the chosen approach, and the
   most important constraints/decisions.
2. **Key design decisions** — the most consequential choices made so far, giving the user the
   context they need before evaluating the findings below.
3. **Spec path** — the file location, so the user can read it directly.
4. **Review findings with proposed solutions** — every Critical and Important finding from
   Step 5, each with your proposed fix, so the user can accept, push back on, or ignore each
   independently. Write each in clear, plain language the user can act on without re-reading the
   spec or the raw reviewer output — not a terse restatement of the reviewer's finding:

   > **<finding title>** [Critical|Important]
   > - What it is: <1–3 sentences describing the problem, with enough context to locate it in the spec>
   > - Why it matters: <the impact — what breaks or stays ambiguous for implementation>
   > - Proposed fix: <the concrete change you'd make>

   List Minor findings compactly, one line each (or omit if none are worth the user's time) —
   they don't need the same treatment.
5. **Overall verdict** from this review pass — APPROVED or NEEDS_REVISION.

Then stop and hand control to the user — tell them you're ready to discuss, revise, or move to
implementation whenever they are. Do not apply any fix yet.

### 6b. Discuss and revise

The user drives this part. Expect any mix of:
- Accepting a proposed fix as-is.
- Pushing back on a proposed fix or the finding itself — discuss it, and if they're right, drop
  or change the fix rather than applying it reflexively.
- Adding their own review comments beyond what the agentic reviewer found.
- Asking you to apply some proposed fixes and leave others open.

You are the sole mutator of the spec: apply whatever is agreed upon via Edit, and confirm what
changed. Keep iterating on this discussion for as long as the user wants — there is no fixed
number of rounds and no cap.

### 6c. Next round or approval — the user's call

Once the user is satisfied with the current round of changes, ask explicitly what they want to
do next (don't assume):
- **Run another `sdd-spec-review` pass** — a fresh invocation, back to Step 5. Only do this when
  the user asks for it; never re-run the agentic review automatically.
- **Approve as final** — stop here. Do not derive tasks. Do not implement. Suggest the user
  invoke `sdd-implement` (optionally `--worktree`) to proceed.

## Principles

- The spec describes *what* and *why* plus architectural decisions — never *how* or *in what
  order*. The detailed implementation is the implementer's job.
- Surface consequential, tradeoff-bearing decisions to the user (with options + a
  recommendation) before writing the spec — never bake in an unspecified posture, such as a
  security/robustness stance, silently. Decisions with no meaningful tradeoff stay with the implementer.
- Functional and non-functional requirements both belong in the spec.
- The spec is ephemeral and lives in the repo root as `spec-<slug>.md`; never delete it.
- You own the review loop and the human gate, and you are the only skill that edits the spec.
- Run exactly one automatic agentic review pass (Step 5) before handing control to the user —
  never self-review, never auto-apply fixes, never auto-loop past that first pass.
- Present every Critical/Important finding with a proposed fix, but leave the decision to apply
  it to the user — never fix silently.
- The user controls the pace: what to accept, push back on, or add themselves, and whether
  another review round runs or the spec is approved as-is. Only re-review when asked.
- Do not implement anything, even if it seems obvious. Human approval is the gate before
  implementation.