---
name: clarify-spec
description: Use before plan-milestone or plan-slice when a feature or change request is underspecified. Resolve high-impact ambiguity around scope, consumers, security, failure handling, and acceptance criteria before writing the implementation plan.
---

# Clarify Spec

## Purpose

Use after the rough feature idea exists but before technical planning starts.

The job: reduce ambiguity that would otherwise cause bad plans, wrong tests, or rework. A wrong plan based on confident-but-wrong assumptions costs more than the few minutes to clarify.

## When to Run

- A user request lands without a clear consumer.
- A milestone goal is "make it better" or "robust" or "fast" — vague verbs that aren't testable.
- A slice plan is being drafted but key boundaries are unstated.
- A change touches a security/auth surface and the threat model isn't named.
- An upstream port (pi-mono legacy port) leaves architectural intent ambiguous after reading the commit.

If the request is concrete and the consumer is obvious, skip this skill — go straight to `brainstorming` or `spec-first-tdd`.

## Load First

- [`docs/SPEC_FIRST_TDD.md`](../../../../../../docs/SPEC_FIRST_TDD.md) — the constitution.
- [`SPEC.md`](../../../../../../SPEC.md) — sf v3 specification, if relevant.
- `.sf/REQUIREMENTS.md` — current Active requirements.
- `.sf/DECISIONS.md` — locked decisions that constrain the answer.
- `.sf/PROJECT.md` — project intent.

## Clarification Priorities

Resolve in this order — highest value first, lowest second:

1. **Primary user / operator** — who initiates this in production?
2. **Production consumer** — which code path depends on it? (`rg` for callers if unsure)
3. **In scope vs out of scope** — what is this change *not* covering?
4. **Failure expectations** — what happens when dependencies fail; is degradation visible to the user?
5. **Security expectations** — auth, tokens, command injection, secret exposure surface.
6. **Measurable acceptance criteria** — observable behaviour, not vague verbs.

If the change touches secrets, auth, or sandbox/permission boundaries: clarify the threat model explicitly. If it touches the auto-loop or worktree management: clarify recovery semantics on crash.

## Question Rules

- **One question per turn.** Avoid serial questioning if the user signals impatience.
- **Prefer multiple-choice** over open-ended when you can enumerate plausible answers — easier to answer, easier to record.
- **Highest-impact unknowns first.** Don't ask about technical stack choices unless they affect correctness.
- **Don't ask low-value style questions.** Style is a follow-up; correctness comes first.
- **Make reasonable assumptions on low-impact details** and state them — `assuming X unless you say otherwise`. The user can correct cheaply.

## Output

Once enough clarity exists for safe planning, produce:

```markdown
## Clarified Spec — <feature/change name>

- **Goal**:
- **Primary user/operator**:
- **Production consumer**:
- **In scope**:
- **Out of scope**:
- **Security expectations**:
- **Failure handling expectations**:
- **Acceptance criteria** (testable):
  - [ ] ...
- **Open questions still deferred** (with default assumption):
  - ...
```

For substantial existing-feature changes, also write a change proposal:

`.sf/active/<unit-id>/proposal.md` (or, before a milestone exists, `.sf/proposals/YYYY-MM-DD-<slug>.md`).

The proposal lists requirement deltas:

- `ADDED:` new requirement or capability.
- `MODIFIED:` existing requirement contract changed.
- `REMOVED:` previously required behaviour deleted.
- `RENAMED:` symbol/file/route renamed (with old → new mapping).

## Stop Conditions

Stop clarifying once:

- The next planning step is safe — `plan-milestone` or `plan-slice` will not produce a wrong plan from these answers.
- All remaining unknowns are low-impact and can be defaulted.
- Continued questioning would drift into solution design (that belongs in `brainstorming`).

## Rules

- Do not guess where ambiguity changes scope or safety.
- Do make reasonable assumptions on low-impact details — and state them.
- Stop clarifying once the next planning step is safe.
- Record the clarified spec into the unit's context before starting `plan-milestone` so the planner builds on the right contract.
