Clarify

Clarify

Produce a requirements + acceptance-criteria artifact that pins down what success looks like, so a planner never has to guess. The bar: every requirement is measurable and every acceptance criterion is checkable — you could hand the artifact to someone else and they'd build the right thing. This is a peer phase to plan, not its parent: it grounds itself in the code via explore, then hands its artifact to plan. It does not design the implementation and does not invoke plan.

Process

1. Resolve from the codebase before asking. If a question's answer is discoverable in the code — how a thing currently works, what the existing convention is, where an integration point lives — call explore (dispatch a sub-agent when available; otherwise do it inline) and find it. Only ask the user what you genuinely cannot determine. Bothering them with a discoverable fact erodes trust.

2. Form an explicit hypothesis of the whole task. Write down, for yourself, the outcome you think they want and the success criteria you'd accept. This is what you'll test against the stop condition — and it makes your questions sharper.

3. Walk the coverage checklist to find the real gaps. Probe each dimension; skip the ones the code or the request already settle:

   • Edge cases — empty/missing/malformed input, boundaries, concurrency, large scale.
   • Error handling — what should fail loudly, what should degrade, what the user sees on failure.
   • Integration points — callers, callees, schemas, events, and contracts this touches.
   • Scope boundaries — what is explicitly in vs. out; where this task ends.
   • Design preferences — conventions, libraries, patterns the user wants honored or avoided.
   • Backward compatibility — existing data, APIs, configs, behavior that must keep working.
   • Performance needs — latency/throughput/memory targets, and on which path.

4. Interview one question at a time. Asking several at once is bewildering — never dump a list. Each question carries your recommended default AND your current hypothesis, made visible:

   Q: Should the cache invalidate on write, or expire on a TTL? GUESS: TTL — the call site tolerates staleness and write-through adds lock contention here.

   Lead with the highest-leverage unknown (the one whose answer most changes the plan). Ask the recommended default as a yes/no when you can, so the user can confirm with a word.

5. Reframe every vague requirement into a measurable one. A requirement you can't test isn't a requirement. Convert runtime words into numbers and conditions:

   • "make it faster" → "p95 < 200ms on the cold path under N concurrent requests"
   • "handle errors gracefully" → "on a 5xx from X, retry twice then surface a typed error to the caller"
   • "clean up the API" → "remove deprecated field Y; no caller in the repo references it"

6. Apply the stop condition (~95% confidence). Stop interviewing when you can predict how the user would react to your next three questions — i.e. their answers wouldn't change the artifact. Don't pad with low-value questions once you're there; don't stop early while a checklist dimension is still genuinely open.

7. Write the artifact in the schema below and hand it to plan. List anything still unresolved under Open assumptions with the default you're proceeding on — never silently pick.

Reject vague delegation

"Sounds good", "whatever you think", "you decide" is not a sign-off — it's an unanswered question. Do not bank it as confidence. Restate your concrete recommendation and get an explicit yes:

You said "whatever you think." To be explicit: I'll expire on a 60s TTL and not invalidate on write. Good to lock that in, or do you want write-through? (Y/n)

If the user truly defers, record it as a resolved assumption with your chosen default and the reason — so the artifact still reads as a decision, not a shrug.

Output schema (the artifact)

# Clarified: <task>
## Outcome            — the one-sentence result the user actually wants
## Primary user       — who consumes this and in what workflow
## Why now            — the trigger / pain motivating it (1–2 lines; omit if there's no clear one)
## Success criteria    — testable, checkable list; each item a verifiable assertion
  - [ ] <measurable criterion, e.g. "p95 < 200ms on cold path">
## Constraints        — must-honor conventions, libraries, compat, perf budgets
## Out of scope       — explicitly excluded, so plan doesn't wander
## Open assumptions   — unresolved items + the default each proceeds on, and why

Every Success criterion must be checkable by a test, a command, or an unambiguous observation — never "works well" or "is robust". If you can't state how you'd verify it, it isn't done. State each as an observable outcome (what must be true), never the mechanism that achieves it — "on a 5xx, the caller sees a typed error within 2 retries" is an outcome; how to implement the retry belongs to plan. When a measurable reframe starts naming structure or an algorithm, you've crossed into design; pull back to the outcome.

Red flags

• Asking the user something explore could have answered from the codebase.
• Dumping several questions at once instead of one at a time.
• A question without a visible GUESS and a recommended default.
• A success criterion that isn't measurable ("fast", "clean", "robust", "user-friendly").
• Banking "sounds good" / "whatever you think" as confidence instead of restating and confirming.
• Silently choosing when uncertain instead of recording an Open assumption with its default.
• Designing the implementation, or invoking plan — both are out of scope for clarify.
• Interviewing past the stop condition, or stopping while a checklist dimension is still open.

Verification checklist

• Every discoverable fact was resolved via explore, not asked of the user.
• Questions were asked one at a time, each with a visible GUESS and a recommended default.
• The coverage checklist was walked; each dimension is settled or listed under Open assumptions.
• Every Success criterion is testable/checkable — no vague adjectives.
• No vague delegation was banked as confidence; deferrals are recorded as resolved assumptions.
• The artifact follows the schema and is self-contained enough for plan to consume directly.
• The skill stayed in scope: no implementation design, no plan invocation.