Clarify Mode — Bounded Refinement Pass
Run this pass before finalizing the phased plan (Step 6) to resolve plan-changing ambiguity. Work high-level → detailed. This is the single sanctioned place to raise questions — bounded, not a gate.
When to run
Run the ambiguity scan for any task that will produce a multi-phase plan. This is the default for multi-phase work — the scan is a silent mental pass, not a ceremony.
Quick-exit: Skip for single-phase / trivially-scoped tasks where scope is self-evident (e.g., "fix this typo", "bump version to X", "rename Y to Z").
The ≤5 cap is a ceiling, never a target. Fewer is better.
Two delivery modes
Determine which mode you are in before proceeding:
- Subagent (spawned by the Conductor or another agent): you CANNOT prompt the user
directly. Return your plan draft and append an
## Open clarifying questionsblock (format below). Do NOT try to ask interactively. - Direct invocation (user ran you directly): ask the user via conversational turns, one question at a time where an answer informs the next.
- If unsure which mode you are in, assume subagent and return questions.
Ambiguity scan
Before collecting [?] markers, silently scan the task against these common ambiguity
patterns. Only surface items where the answer isn't determinable from the user's prompt
or the codebase:
- Scope boundaries — what's in, what's explicitly out?
- Backward compatibility — does this change behavior for existing consumers?
- Error/edge-case strategy — fail loudly or degrade gracefully?
- Approach choice — multiple valid approaches exist; has one been decided?
- Implicit dependencies — ordering or environment assumptions not stated?
If the scan surfaces nothing, proceed to phasing without asking questions. Do not report "scan clean" — just move on.
How to run the pass
- Collect plan-changing ambiguities — prefer existing
[?]markers over new ones. - Ask ≤5 targeted questions, highest-impact first.
- Where an answer to one question informs another, ask one at a time (in sequence). Batch only mutually independent questions.
- Stop early once unambiguous — never force 5 questions.
- Record each answer and clear the matching
[?]marker. - Finalize and save.
## Open clarifying questions block format (subagent mode)
Append this block to your return after the plan draft:
## Open clarifying questions 1. [highest-impact question] — affects: [what part of the plan] 2. [next question, if independent of #1]
Recording format (task.md)
Add a dated ## Clarifications subsection under Research Findings before the phase
table is finalized:
## Clarifications ### YYYY-MM-DD - Q: [question] → A: [user's answer] - Q: [deferred question] → Assumed: [assumption made], no answer given
For deferred or unanswered items, record the assumption explicitly. Never silently guess a plan-changing ambiguity — record it so the Builder and Reviewer can see it.
