Clarify

Clarify Protocol

This protocol is loaded on demand by the architect runtime. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.

MODE: CLARIFY

Ambiguous request → Run the clarification funnel Clear request → MODE: DISCOVER

Clarification Funnel

Before surfacing any clarification question to the user, the architect MUST run this four-stage funnel. The goal is to limit unnecessary user interruption, not planning completeness.

Stage 1: Inventory All Material Uncertainties

Identify ALL uncertainties that could affect:

• Scope boundaries
• User-visible behavior
• Destructive behavior or data loss
• Security/privacy posture
• Backward compatibility
• Migrations or rollout strategy
• Cost/performance tradeoffs
• Operational complexity
• QA gate selection or enforcement strictness
• Architecture choice among materially different paths
• Dependency or platform assumptions

There is NO hard cap on the internal inventory. Record every material uncertainty found.

Stage 2: Classify Each Uncertainty

Classify each item as exactly one of:

• self_resolved: answered from the user request, spec, plan, codebase reality check, .swarm/context.md, repo conventions, or an informed default. If the default is not directly supported by user request, spec, or recorded context, classify as user_decision rather than self_resolved.
• critic_resolved: sent to Critic Sounding Board and resolved by the critic.
• research_needed: needs SME/explorer/domain lookup before user escalation. Important: If research is ongoing, apply a fixed 5-minute protocol budget to research_needed. If research does not complete before the budget expires, automatically reclassify the item to user_decision with a note that research was incomplete, then surface it to the user. This prevents the clarification funnel from stalling while waiting for external research.
• user_decision: only the user can decide because it affects product scope, risk tolerance, policy, budget, UX, rollout, or destructive behavior.
• deferred_nonblocking: useful follow-up detail that does not block a correct initial plan and can be explicitly recorded as an assumption or follow-up.

Stage 3: Consult Critic Sounding Board

Before asking the user any clarification question, the architect MUST consult critic_sounding_board with the candidate question set and context.

For each item classified as research_needed or user_decision in Stage 2, send it to the critic. The critic responds with a verdict from the SoundingBoardVerdict enum (UNNECESSARY | RESOLVE | REPHRASE | APPROVED). The mapping between critic verdicts and funnel actions is:

Hard constraint: Items in the Always-Surface Categories list (below) MUST NOT receive UNNECESSARY/DROP from the critic — only REPHRASE or APPROVED/ASK_USER are allowed. If the critic attempts to UNNECESSARY/DROP an always-surface item, override to APPROVED/ASK_USER.

Overconfidence guard: If the critic attempts to self-resolve an item by supplying an answer (verdict RESOLVE) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as user_decision rather than self_resolved. Unsupported defaults must not be silently accepted.

Update classifications based on critic response:

• UNNECESSARY/DROP → reclassify as self_resolved and record the reason.
• RESOLVE → reclassify as critic_resolved and record the answer as an assumption.
• REPHRASE → update the question wording and keep as candidate.
• APPROVED/ASK_USER → confirm as user_decision.

Record all resolved items as explicit assumptions before proceeding.