/elaborate-spec

name: elaborate-spec
model: opus
effort: standard
description: Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn "I want X" into a concrete spec.
# story: e24s01

Elaborate Spec

Turn a rough idea into a clear specification through focused dialogue. No code is written during this skill — the output is shared understanding and a refined problem statement.

> **HARD GATE** — Do NOT proceed with planning or implementation until the problem space is clearly understood. Success criteria, actors, and scope must be explicit before drafting a plan.

Process

1. Listen first

Let the user describe their idea in their own words. Do not interrupt or redirect. Take notes on:

• The core problem they're trying to solve
• Who is affected (actors)
• What success looks like to them
• Any constraints they've already identified

2. Ask clarifying questions

Ask one question at a time. Work through these areas:

**Problem clarity**

• What is the current behavior (or lack of behavior) that prompted this?
• Who experiences this problem? How often?
• What's the cost of not solving it?

**Solution boundaries**

• What is explicitly IN scope?
• What is explicitly OUT of scope?
• Are there existing solutions (internal or external) this replaces or integrates with?

**Success criteria**

• How will you know this is done?
• What does the happy path look like end-to-end?
• What are the key failure modes to handle?

**Constraints**

• Any performance requirements?
• Any compatibility constraints (existing APIs, data formats)?
• Any non-negotiable implementation decisions already made?

2.5. Multiple Interpretations (HARD GATE)

> **HARD GATE** — If the request admits ≥2 valid interpretations, do NOT guess. You must list them and ask the user to choose before proceeding. Proceeding with unresolved ambiguity is a failure of integrity.

Present the options clearly: > "I see two ways to read this: > 1. [Interpretation A] — my recommendation because [reason] > 2. [Interpretation B] > Which is closer to what you mean?"

3. Surface hidden assumptions

Once the user has answered the main questions, probe for assumptions:

• "You mentioned X — does that mean Y is also true?"
• "What happens when Z fails?"
• "Is this for internal users, external users, or both?"

4. Synthesize and confirm

Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](../../docs/countable-story-format.md):

• The problem (feeds into §1 Business narrative)
• The solution and main flow (feeds into §5)
• The key constraints and alternative flows (feeds into §6)
• The success criteria (feeds into §17 Gherkin)
• What's out of scope (feeds into §18)

Ask: "Is this an accurate summary? Anything missing or wrong?"

5. Write specs/planning-context.yaml

After the user confirms the summary in step 4, persist the key decisions:

# specs/planning-context.yaml — written by elaborate-spec; consumed by scope-work and slice-tasks
feature_name: "<from step 1>"
problem_statement: "<one paragraph>"
constraints:
  - "<constraint 1>"
out_of_scope:
  - "<excluded item 1>"
key_decisions:
  - decision: "<what was decided>"
    rationale: "<why>"

If `specs/planning-context.yaml` already exists, ask: `"Planning context from a prior session exists. Update it? [Y/n]"`. Overwrite on Y; leave unchanged on N.

6. Suggest next skill

Once the spec is clear, recommend the next step:

• If domain model needs work → `model-domain`
• If ready to plan → `plan-release` (creates epic capsules with `epic.yaml` + story `.md` + `-tasks.yaml`) then `plan-work` per story
• If a spike is needed first → `spike-prototype`
• If architecture decisions are needed → `deepen-architecture` or `grill-me`
• If the plan depends on a specific library or API → `grill-me` in docs mode