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

name, description, model, effort, allowed-tools

name	description	model	effort	allowed-tools
sdd-plan	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".	opus	high	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.

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

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