/clarify

name: clarify
model: inherit
effort: high
agents: [devils-advocate]
description: >
  Use to run an ambiguity sweep over a written spec.md and close every under-specified
  point before planning or design proceeds — so two engineers can't reasonably build
  different things from the same spec. Triggers on "clarify {slug}", "find ambiguities in
  {slug}", "is the spec ready", "sharpen the spec", "/sdd:clarify {slug}",
  "прояснити специфікацію", "знайди неоднозначності {slug}", "чи готова специфікація".
  Re-reads the spec, dispatches a clean-context devil's-advocate subagent to list where the
  spec forks, then for each ambiguity runs AskUserQuestion to RESOLVE it (tighten §1/§5/§6
  in place) or DEFER it (→ §8 Open questions with owner+due). Output: an updated
  docs/features/{slug}/spec.md with every ambiguity resolved or deferred — none dangling.
  Hard-refuse if spec.md is missing.

Skill: clarify

Ambiguity sweep over a written `spec.md`. It hunts the spec for under-specified points — vague terms, unmeasured NFRs, AC missing error/authz/edge behavior, unstated assumptions, conflicting requirements, undefined domain terms, missing actors, scope creep — then dispatches a **clean-context devil's-advocate subagent** that re-reads the spec fresh and answers one question: *where would two engineers reasonably build different things from this?* Each ambiguity it surfaces is closed with the user: either **resolved** (the spec is tightened in place) or **deferred** (a §8 Open-Questions row with owner + due). It exists so `glossary` / `design` never proceed on an ambiguous spec.

This is a sweep, not a full authoring stage — it does **not** run the shared Socratic loop or the coherence critic. Its shared dependencies: → [`../_shared/critic.md`](../_shared/critic.md) (clean-context **dispatch discipline** only — the subagent here hunts AMBIGUITY, not coherence drift) · [`../_shared/ask-style.md`](../_shared/ask-style.md) (resolve/defer question phrasing).

Depth governs how aggressively the sweep hunts + the per-finding question volume → [`../_shared/interview-depth.md`](../_shared/interview-depth.md). (Every surfaced ambiguity is still Resolved or Deferred at every level — that's a floor, not a dial.)

Spec tightenings follow `artifact_language` — but the **existing spec's language wins** over the setting (never retro-translate mid-sweep); headings and machine tokens stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md).

Owner

PM + Tech Lead (the spec's co-authors resolve their own ambiguities). PM owns vague-term / scope / missing-actor calls; Tech Lead owns unmeasured-NFR / under-specified-AC / conflicting-requirement calls.

Inputs

• `<slug>` — same feature slug used by `specify`.
• **Gate (hard-refuse if missing):** `docs/features/<slug>/spec.md`. Absent → STOP and point: «run `specify <slug>` first — clarify sharpens an existing spec, it does not write one».
• (Optional) `CONTEXT.md` — two-level: read **both** repo-root (project-wide) and `docs/features/<slug>/CONTEXT.md` (feature-scoped; wins on conflict) → [`../glossary/SKILL.md`](../glossary/SKILL.md); if present, `## Glossary` is canonical; an "undefined-term" finding for a word already glossed at either level is a false positive (drop it).
• **Fast lane (XS/S):** when `specify` produced zero §8 open questions and flagged no ambiguous AC, the skip of this stage is offered by **`specify`'s handoff** (→ the fast lane in [`../_shared/size-matrix.md`](../_shared/size-matrix.md)) — the user takes it there; clarify itself never auto-skips.

Protocol

1. **Gate + set interview depth.** `test -f docs/features/<slug>/spec.md` → missing = refuse with the pointer above. Read the spec (and `## Glossary` from both root `CONTEXT.md` and `docs/features/<slug>/CONTEXT.md` if present — per-feature wins — to suppress false "undefined-term" hits). **Then set the interview depth (the opening question):** read `interview_depth` from `.claude/sdd.local.md` if present (else default medium), and — unless a `--depth=easy|medium|hard` arg was passed — ask ONE depth-selection `AskUserQuestion` phrased per [`../_shared/ask-style.md`](../_shared/ask-style.md), with the saved/medium value as the «(Recommended)» first option. The level tunes how adversarially the sweep + subagent hunt (easy: only build-divergence that changes behavior, with assumptions stated; medium: balanced; hard: adversarial, every fork surfaced) and the per-finding question volume → [`../_shared/interview-depth.md`](../_shared/interview-depth.md). 2. **First-pass self-sweep.** Walk the spec against the eight ambiguity classes in [`./references/ambiguity-checks.md`](./references/ambiguity-checks.md) (vague-term / unmeasured-NFR / under-specified-AC / unstated-assumption / conflicting-requirement / undefined-term / missing-actor / scope-creep). Note candidate findings with a `§ref` each — do not edit yet. 3. **Devil's-advocate subagent (the core mechanic).** Dispatch the [`devils-advocate`](../../agents/devils-advocate.md) agent — `subagent_type: "sdd:devils-advocate"` (model per `judgment_model`, roster default `opus`; effort `high`; clean context — it never saw this conversation). Pass only the slug + the spec path; it Reads `spec.md` (and `CONTEXT.md`) itself — inline nothing — and returns "two engineers would diverge here" findings. The dispatch follows the contract in [`../_shared/agent-roster.md`](../_shared/agent-roster.md) (clean-isolated context, cited findings, `NO_AMBIGUITIES` if none). If `devils-advocate` is unavailable at runtime, fall back to a `general-purpose` Agent with the prompt body in [`./references/ambiguity-checks.md`](./references/ambiguity-checks.md). 4. **Merge + dedupe.** Union the self-sweep (step 2) with the subagent findings (step 3); collapse duplicates (same `§ref` + same class). Keep the highest-impact first (conflicting-requirement > under-specified-AC > unmeasured-NFR > undefined-term > missing-actor > scope-