sdd-clarify

SDD Clarify — ask well, build once

The cheapest token is the one you don't spend re-doing work. A vague request implemented blind burns iterations (implement → wrong → re-implement → re-review). This skill front-loads the ambiguity: a short, sharp clarification pass turns a fuzzy ask into a well-scoped SDD change, so the implement/review loop runs once. Modeled on GitHub Spec-Kit's /speckit.clarify and Matt Pocock's grill-me skill (interview until shared understanding, resolving each branch of the decision tree, with a recommended answer per question) — adapted to be token-frugal.

When to use

On any feature/bug request, BEFORE proposing a spec or touching code. It is the step that feeds /opsx:propose (or the workflow's spec phase) a goal that's actually pinned down.

The clarify pass

1. Gather context cheaply first. Read only what's needed to know what's ALREADY decided

by the code/specs — existing modules, related specs, conventions. Never ask the user something the repo already answers. (Use a cheap read/locate, not a deep dive.)

1. Scan for ambiguity across these dimensions (Spec-Kit's set) — keep only the ones that

are genuinely unresolved AND change what you'd build:

• Functional scope & boundaries (what's in / explicitly out)
• Data model / entities / persistence
• Integration & dependencies (which services/events/contracts it touches)
• Edge cases & failure behavior (fail-open? errors? empty/limits?)
• Non-functional (latency budget, security/authz, idempotency)
• Terminology / domain (disambiguate overloaded terms — e.g. bill vs invoice)

1. Ask the questions — decision-tree aware (grill-me), but token-frugal. Order them by the

decision tree: scope decisions first, they gate the rest. Batch the INDEPENDENT questions into ONE AskUserQuestion call (2–4 selectable options each, the RECOMMENDED option first and labeled, so answering is a click, not an essay) — that saves round-trips. When an answer opens a genuinely NEW dependent branch (a follow-up that only makes sense given that answer), do ONE more short round for it — resolve each branch, don't guess across it. Never batch two questions that depend on each other; never ask what the code already decides or what has an obvious default (state the default and move on). If the request is unambiguous, ask nothing and go straight to step 5. Cap the whole pass at ~2 rounds — grilling forever is its own waste.

1. Fold the answers into the proposal. Every answer becomes an explicit line in the

OpenSpec proposal/spec (scope, decisions, edge cases) — the spec, not chat, is the record.

1. Route to SDD:

• Small / single-file / bugfix → /opsx:propose then /opsx:apply.
• Large / cross-cutting / chat-surface → launch the sdd-feature-flow workflow with the

clarified goal (it can't ask the user mid-run, so the clarity must come from HERE).

1. Review at PR time is not this skill's job — it's the pre-pr-greptile skill: when the

change is implemented and you go to open the PR, that runs greptile review, verifies the diff match, triages, and gates the PR. Clarify → spec → implement → greptile review → PR.

Guardrails

• Don't over-ask. Over-questioning is its own waste (of the user's time AND tokens). 3–4

sharp questions max; zero if the ask is clear. Recommended-first options so the user can one-click the default.

• Never invent facts to fill a gap — if something is unknown and load-bearing, ask; if it's

unknown and minor, pick a sensible default and state it in the spec.

• Ambiguity resolved here MUST be written into the OpenSpec artifacts, not left in chat.
• Respect the SDD gate: production-source edits still require the active change this produces.