Overview
Loss of control in requirement clarification takes only two forms:Asking too little— treating unconfirmed assumptions as conclusions and acting on them;Asking too much— replacing convergence with exhaustive boundary enumeration, turning the user into a Q&A machine.
This protocol turns clarification into a convergent process withprerequisites, levels, a ledger, a budget, and an exit.
SSOT boundary: the global prompt retains only a one-line pointer to stay present each round; the complete protocol for clarification and convergence is governed by this skill, and details are not duplicated at the global layer.
1. Terminology First — Global Prerequisite
- First define one by one thecore terms, scope, and ambiguity-prone points, register them in the glossary section of the requirement confirmation document (RFC) or the plan file, then use the unified terminology to clarify requirements and boundaries.
- Terminology issues are aglobal prerequisiteand are exempt from the "dependency strength × implementation impact" grading below—they must notbe converted into default assumptions on the grounds of being judged locally low-impact.
- Scope is bounded by "ambiguity-prone",expansion into an exhaustive vocabulary list is prohibited。
- Order gate: if terminology is not aligned, do not proceed to requirement and boundary clarification.
2. Question Sequencing
- Clarifying questions are ordered by "dependency strength × implementation impact".
- HIGH(affects implementation) enters this round's question list.
- LOW(affects implementation details only) goes directly todefault assumptionand is registered, without consuming user attention.
- When user decisions are needed, give preference to 2–3 feasible options (pros and cons comparison + recommendation rationale), guiding the user to make multiple-choice decisions rather than open-ended questions.
3. Decision Ledger
Decided items, excluded boundaries, and default assumptions must beimmediatelyregistered in the plan file or checkpoint; never left only in the conversation:
| Category | Registered content | Must state |
|---|---|---|
| Decided items | The conclusion itself | Source (user ruling / evidence) |
| Excluded boundaries | The excluded options or scope | Basis for exclusion |
| Default assumptions | Values adopted without asking | Impact level and vetoability |
- Deduplication discipline: it is prohibited to reopen an already-excluded boundary with different wording—repeated questioning is a violation。
- Early convergence: when converging early, branches judged low-impact and converted into default assumptions must be registered; unregistered means not converged.
4. Convergence Rule & Three-Item Convergence Self-Check
At each milestone (default: at the end of each round of questioning), perform ano-new-questionsself-check that answers only three items:
- Are the core business objectives and processes still unclear in any respect?
- Are the key boundaries and exceptional cases still unconfirmed in any respect?
- Are there contradictory descriptions among the decided items?
- All three negative (no new information increment) means convergence: close out the main trunk, register the remaining boundaries as explicit default assumptions, and output the requirements confirmation document;do not use exhaustive questioning as the exit。
- If any is yes, continue, and the next round of questions must target that item.
- Do not self-certify convergence with "no more questions" — convergence must be evidenced by the ledger in the table above.
5. Circuit Breakers & Escalation
| Layer | Budget | Action on cap |
|---|---|---|
| Error layer | 3 consecutive attempts at the same error | STOP → RECORD; Heavy Track viaevidence gatingmay re-enter a limited number of times (≤2 rounds × ≤2 attempts); other channels directly ASK & ESCALATE |
| Review layer | Delta Re-Loop ≤ 5 rounds | Stop adding rounds, report upward with existing evidence, do not seek reassurance by adding rounds |
| Questioning layer | This section | Budget exhausted without convergence → escalate to human adjudication |
The four re-entry gating criteria (new assumption / new external evidence / not a rewording / budget not exhausted) and the cost cap min(任务总预算 × 25%, 剩余预算 ÷ 3) see goal-loop the failure-recovery-protocol of the skill.
When escalating, objectively state four items to the user: current status, verified information, current bottleneck, and the specific fork requiring adjudication.
6. Explicit Reasoning
Before executing key architectural decisions, complex refactoring, or multi-step tasks, use a thinking block in the output to lay out the reasoning (constraints → candidates → trade-offs → conclusion), ensuring the logic is self-consistent before writing.
When to use / when not to use
Use: the goal is macro or vague; multiple technical paths exist; during multi-round Q&A; a settled item is reopened in different wording; a trade-off is needed between "asking the user" and "registering a default assumption"; clarification rounds show signs of getting out of control.
Do not use: single-file minor edits, direct execution of clear instructions, read-only retrieval Q&A — just do the work.
Deliverables & Entry Points
This section is the mechanical entry point to the body of the protocol. The protocol consists of only this one file; the following files are itsexpansions, skeletons, and validators, and introduce no new policy.
- Expansions：references/decision-ledger.md refine the ledger discipline of §3 into required fields for the three types of registration, the deduplication decision formula, and the criteria for converting low-impact branches into default assumptions;references/convergence-checklist.md refine the three-item self-check of §4 into per-question decision criteria and counterexample comparisons of "not counting as convergence".
- Skeletons：templates/decision-ledger-template.md can be dropped directly into the plan file;templates/requirement-confirmation-template.md is the requirements confirmation document skeleton (glossary / settled items / excluded boundaries / default assumptions / convergence conclusion / forks pending adjudication).
- Validation：scripts/check-decision-ledger.sh mechanically validates the ledger structure (offline, read-only; exit code 0 compliant / 1 non-compliant / 2 usage error); run it once before the §4 self-check:
bash scripts/check-decision-ledger.sh <台账文件>。 - Regression：tests/test_clarification_protocol_contract.py guards the above deliverable surfaces and hard constraints, run
python3 -m pytest skills/clarification-protocol/tests -q。