spec-loop-clarify-task

Use this skill only when material unresolved questions, decision criteria, or option trade-offs block safe planning, approval, design updates, ADR work, or implementation.

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

When clarification ends, return control to the invoking workflow:

Clarification stays in the phase of the invoking workflow:

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

Handle obvious typo fixes, trivial one-word disambiguations, and simple factual confirmations inline when they would not materially change scope, behavior, policy, conceptual model, conceptual contract boundaries, acceptance logic, route, Design, or Test specification.

These are outside the grilling protocol: no grill-level notice, decision batches, or / format.

If such a point turns out to have a material design consequence, resume normal clarification.

For each unresolved point:

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 material.

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 instead.

If drafting or reviewing Design exposes a new material boundary question, return to clarification before continuing.

Clarification uses three tools:

Use the current clarification grill level already in force for the work item when one exists. Otherwise, if no user, session, or project default is in force, default to .

Keep the grill level implicit unless clarification is likely to require more than 3 user-facing clarification steps. A clarification step is one decision batch or one block. Plain confirmations do not count.

If the threshold is exceeded, state the current grill level once for that work item:

If the need for more than 3 clarification steps becomes clear only later, give the notice then before continuing. Do not repeat it unless the user asks, the level changes, or clarification starts for a different work item.

The grill level affects surfacing and question frequency only. It does not change the definition of a material unresolved question or the need to preserve final clarification state.

Select unresolved branches by descending importance and uncertainty. Traverse the selected branch depth first. Start with a brief map of the most important visible unresolved branches and which branch you will address first.

For directly resolved decisions:

A surfaced decision batch must contain at most 6 decisions.

At each clarification step, present either:

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.

Clarification always works against one governing artifact:

Keep final clarification decisions in the governing artifact's section.

In task artifacts, follow : place immediately after and record each final clarification decision as

In ADRs, follow : keep as compact ADR-relevant bullets supporting the chosen decision. Treat it as the ADR's authoritative decision-and-reason ledger.

Keep only accepted final decisions there. Do not keep open questions, options, confidence values, or transient notes.

Clarification is cross-cutting. When a decision becomes final, update 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 clarification 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 clarification state before returning control.

For each surfaced decision in a batch, use:

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

Keep both lines brief. The line must contain the actual answer.

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

For explicit questions, use:

Question: <brief question> Recommendation: <answer> (<N>%) Reason: <brief reason>

If the question is a choice among listed alternatives, use:

Question: <brief question> Recommendation: <letter> (<N>%) Options:

For yes/no questions, use or unless you explicitly list lettered options.

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

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