Spec Loop Clarify Task

Use this skill to discuss, analyze, compare options, stress-test, and resolve important open decisions. A work item is optional. If no task file, ADR, or invoking workflow exists, run clarification as a chat-only discussion.

An important open decision is any open question, choice, criterion, trade-off, credible option, or boundary where different answers could materially change the user's intended conclusion, scope, behavior, policy, conceptual model, conceptual contract boundaries, constraints, route, acceptance logic, verification expectations, Design, Test specification, or the ADR Decision or its justification.

If the current discussion or work item is clearly free of important open decisions, do not use this skill.

This skill is not just for asking questions. Resolve what evidence already determines, record final decisions in the governing artifact when one exists, and ask the user only when user input is still needed.

Prefer this skill over a generic grill-me variant for Spec Loop task creation, task updates, and design updates.

Phase and handoff

Clarification stays in the invoking workflow phase when one exists:

• planning clarification stays in PLAN;
• ADR clarification stays in ADR work;
• implementation-time clarification follows

spec-loop-implementation-flow/SKILL.md.

If there is no invoking workflow, clarification stays in chat. Do not create or edit a task file, ADR, glossary, or other durable artifact unless the user explicitly says where the result should be captured.

During PLAN or ADR work, revise the governing artifact in place as needed. Executable changes are not allowed.

When this skill ends:

• if an invoking workflow exists, return control to it;
• otherwise, stop with the resolved chat state and any remaining open

questions clearly stated.

Workflow-specific returns:

• task planning resumes spec-loop-plan-task/SKILL.md;
• ADR clarification resumes spec-loop-write-adr/SKILL.md;
• approval-preparation clarification resumes

spec-loop-prepare-implementation-approval/SKILL.md;

• implementation-time clarification resumes

spec-loop-implementation-flow/SKILL.md.

Decision tree

1. Check whether clarification is needed

If no important open decision remains:

• if an invoking workflow exists, return control to it promptly;
• otherwise, end the chat-only clarification promptly; and
• do not start clarification batching or durable-state recording for

this skill.

2. Answer simple cases inline

If the point is an obvious typo fix, trivial one-word disambiguation, or simple factual confirmation, answer directly when the answer would not materially change scope, behavior, policy, boundaries, acceptance logic, route, Design, or Test specification.

Do not use the clarification protocol for these cases.

If the point turns out to matter for the design, continue with normal clarification.

3. Resolve what evidence already determines

For each important open decision, first check whether the answer is already determined by confirmed user choices, current discussion context, existing task materials, glossary language, code, docs, or a low-risk mechanical consequence of those choices.

Treat conflicts between user wording, glossary language, task materials, and code as evidence to surface explicitly.

If a distinction would change whether two concepts are the same thing, different things, or governed by different rules, treat it as important.

Do not use clarification for exact names, wording, labels, field names, enum names, or other cheap-to-change design text when the boundary is already settled. Put that in Design when a design artifact exists; otherwise handle it inline.

If drafting or reviewing Design exposes a new important open decision, return to clarification before continuing.

4. Confirm settled decisions

For settled decisions, use chat confirmation only when the choice should be explicit in the conversation. Artifact storage is handled in Where to store the result.

Use this for user-made choices, mechanical consequences of user input, choices later clarification depends on, or choices where confirmation reduces ambiguity. Do not add confidence or model reasoning. Use:

Recorded: <choice>.

Do not put settled decisions in a decision batch.

5. Propose decisions or ask questions for unsettled decisions

For an important decision not settled by the user or existing materials, choose one outcome:

• Surfaced decision batch: use when the agent can propose a clear

choice and user check or agreement is enough.

• Clarification question: use when user input is still needed before a

choice can be made.

A surfaced decision batch must contain at most 6 proposed decisions. For each proposed decision, use:

Decision: <brief answer> (<N>%) Reason: <brief reason>

Keep both lines brief. The Decision: line must contain the proposed answer.

After a decision batch, ask the user to confirm, question, or disagree, then wait.

Every clarification question must list alternatives. Use this format:

Question: <brief question> Recommended option: <LETTER> (<N>%) Options:

• A. <brief option summary>
• B. <brief option summary>
• C. <brief option summary>

Reason: <brief reason>

For clarification questions:

• Recommended option: must contain only the recommended option letter

and confidence;

• option summaries and explanations belong only in Options: and

Reason:;

• option lines use - <LETTER>. <summary>;
• do not put confidence values on individual option lines;
• for yes/no choices, use option summaries such as A. yes and

B. no.

Before sending any response containing Options:, validate that:

• the Recommended option: line has the exact shape

Recommended option: <LETTER> (<N>%);

• the recommended letter exists in the option list;
• option lines have the exact shape - <LETTER>. <summary>; and
• no option line contains a confidence value.

When the user cleanly confirms a presented option, acknowledge it briefly, such as B recorded or yes recorded.

Clarification effort question

Clarification effort controls the balance between proposed decision batches and clarification questions for decisions not settled by the user or existing materials. It does not control whether a question lists alternatives; every clarification question lists alternatives. It does not change what counts as an important open decision or the need to preserve the final result.

Ask the clarification effort question only when clarification is likely to take more than two substantive steps, or when the decision space is broad enough that user control over detail matters. Do not ask it when clarification is expected to finish within two substantive steps.

A substantive clarification step is either:

• one decision batch; or
• one substantive question about the discussion or work item.

Before the clarification effort question, briefly say what needs clarification and why. That scope sentence and the clarification effort question do not count as substantive steps.

The clarification effort question may come before any substantive step or after one or more steps. These are all valid:

• clarification effort question, 1, 2, 3;
• 1, clarification effort question, 2, 3;
• 1, 2, clarification effort question, 3, 4, 5.

The clarification effort question is a special case of the required alternatives format. Use this fixed template; vary only the recommended option, confidence value, and reason:

Question: How involved do you want to be in this clarification session? Recommended option: <A/B/C/D> (<N>%) Options:

• A. Low effort: prefer proposed decision batches where safe; ask only when user input is needed.
• B. Normal effort: propose clear choices; ask when uncertain or preference-sensitive.
• C. High effort: ask when uncertain or when the decision is among the most important; use batches for straightforward choices.
• D. Exhaustive: ask about every important unsettled decision; record settled decisions directly.

Reason: <brief reason for the recommended option> You can change this later by saying "ask fewer questions", "ask more questions", or "ask about every important decision".

Recommend the option that best fits the situation. Use Normal effort when there is no stronger reason for another recommendation.

After asking the clarification effort question, wait for the user's next reply. If that reply does not answer it, use the recommended option, say that you are doing so, and continue.

Once set, clarification effort applies to the current clarification run unless the user changes it. For later clarification in the same chat session, ask again if the question is warranted; you may recommend the last selected preference or a different option. Do not silently reuse a previous effort setting as active for a new clarification run. If the user asks to remember the preference, available memory or project instructions may be used.

Treat Low, Normal, High, and Exhaustive as named anchors on a continuum, not as the only possible settings. Interpret "ask fewer questions" and "ask more questions" as relative adjustments along that continuum. Interpret "ask about every important decision" as Exhaustive.

Natural wording such as "grill me more", "grill me heavier", "grill me less", or "grill me lighter" may be interpreted as involvement adjustments, but do not advertise those phrases in user-facing text.

Step order during clarification

Choose open decisions by descending importance and uncertainty. Work through the chosen issue depth first.

At each substantive clarification step, present exactly one of:

• one decision batch; or
• one clarification question.

Do not ask a question before presenting queued decisions it depends on. Do not ask a new question in the same response as a decision batch.

When a response contains a clarification question or decision batch, put that question or decision batch at the end of the message. Put any needed context, evidence, explanation, or status before it. After a decision batch, only the short confirm/question/disagree prompt may follow.

Use Decision: batches only for agent-proposed decisions that need user check or agreement. Do not use them for choices already made by the user or settled by existing materials.

Where to store the result

Clarification may have a governing artifact, or it may be chat-only.

Use these storage rules:

• Task-governed clarification: store final resolved decisions in the

task artifact.

• ADR-governed clarification: store final resolved decisions in the ADR.
• Chat-only clarification: keep decisions in chat until the user says

where to capture them. At the end of chat-only clarification, ask whether the outcome should be saved and where.

For chat-only clarification, do not create, select, or infer a durable storage destination. Before writing the outcome anywhere, ask the user where to capture it.

Store only final resolved content in the governing artifact when one exists. Do not store open questions, confidence values, or transient notes.

In task artifacts:

• keep final resolved decisions in Analysis;
• follow spec-loop-plan-task/common-task-guidance.md;
• place Analysis immediately after Research; and
• record each final clarification decision as

- <decision> because <reason>.

In ADRs, do not force all final resolved content into Analysis. Follow spec-loop-write-adr/adr-format.md:

• put pre-decision facts in Context;
• put credible competing options in Alternatives;
• put the chosen outcome in Decision; and
• keep only the ADR-relevant reasoning subset in Analysis as compact

bullets supporting the chosen decision.

For ADRs, keep credible alternatives in Alternatives, not duplicated inside Analysis.

This skill is cross-cutting. When a decision becomes final and a governing artifact exists, update the correct section or sections above and every affected section of the governing artifact.

If clarification resolves or changes shared domain terms, note the required glossary follow-up in the active task when one exists or is being prepared.

For task-controlled work, do not let final resolved state live only in chat once that becomes unsafe. Promote to the task-file path before chat-only storage becomes unsafe, and always sync the final resolved state before returning control. This rule does not convert standalone chat-only discussion into task-controlled work.

Exit

Before handing work back to the invoking workflow, confirm that:

• no important open decision remains in the part of the work item being

handed back;

• glossary conflicts and code/docs contradictions have been resolved or

explicitly surfaced;

• required glossary follow-up has been noted when relevant; and
• the governing artifact matches the final resolved state.