Spec Clarification Challenge

Spec Clarification Challenge

Purpose

Surface the few questions that could still make spec.md review-readiness dishonest.

This skill is a formal gate inside specification, not a workflow phase, not the mandatory post-spec specification-review gate, and not a second design document. It gives the orchestrator approval-focused questions to answer from evidence, route to targeted expert research, defer explicitly, or record as accepted risk before the spec becomes review-ready. Lean-local Risk Challenge is handled inline in spec.md unless an escalation trigger requires this formal lane. In broad formal clarification, this skill normally runs as one lane in a multi-lane read-only challenger set. Single-lane use is valid only when the orchestrator provides a scoped-down rationale listing the default lenses considered and showing with evidence that omitted lenses cannot change review-readiness.

Outcome-First Operating Rules

• Start by naming the skill-specific outcome, success criteria, constraints, available evidence, and stop rule.
• Treat workflow steps as decision rules, not a ritual checklist. Follow exact order only when this skill or the repository contract makes the sequence an invariant.
• Use the minimum context, references, tools, and validation loops that can change the deliverable; stop expanding when the quality bar is met.
• Before acting, resolve prerequisite discovery, lookup, or artifact reads that the outcome depends on; parallelize only independent evidence gathering and synthesize before the next decision.
• Prefer bounded assumptions and local evidence over broad questioning; ask only when a missing fact would change correctness, ownership, safety, or scope.
• When evidence is missing or conflicting, retry once with a targeted strategy or label the assumption, blocker, or reopen target instead of treating absence as proof.
• Finish only when the requested deliverable is complete in the required shape and verification or a clearly named blocker/residual risk is recorded.

Scope

• inspect candidate decisions that are already close to spec.md review-readiness
• find non-obvious questions that could change scope, acceptance semantics, architecture boundaries, source-of-truth ownership, data/API/security/reliability behavior, failure semantics, rollout, or validation strategy
• classify each question by approval impact and recommend the smallest next action
• keep the output compact enough for direct orchestrator reconciliation
• preserve the escalation boundary: use this formal lane for full-orchestrated or protected-domain approval risk, not for lean-local ceremony
• when used in multi-challenger fan-out, stay inside the assigned lens instead of trying to cover every domain

Boundaries

Do not:

• make final product, architecture, API, data, security, reliability, rollout, or validation decisions
• edit files, write spec.md, update workflow plans, mutate git state, or alter the task ledger or implementation handoff
• ask the human by default; return questions for the orchestrator to reconcile
• produce a parallel design document, task breakdown, or research transcript
• repeat generic checklist prompts such as "what about security?" unless tied to a concrete seam in the candidate decisions
• reopen settled scope without showing why a different answer would change spec approval

Required Input Bundle

Expect a compact bundle from the orchestrator:

• problem frame
• scope and non-goals
• candidate decisions
• constraints and validation expectations
• known assumptions and open questions
• links to relevant research/*.md or lane outputs when they matter
• assigned lens or specialist domain when part of a multi-challenger fan-out
• one concrete approval-critical question for this lane; a lens label alone is insufficient input
• sibling lenses when part of a multi-challenger fan-out
• scoped-down rationale when this is the only lane for a formal challenge that would otherwise look broad; it must list default lenses considered, the retained lane, and why omitted lenses cannot change approval
• confirmation that formal challenge is triggered, or the specific concern that made inline lean Risk Challenge insufficient

If the bundle is too thin to challenge, say what is missing and classify the result as blocking approval rather than guessing. In multi-challenger fan-out, a lens label without a concrete approval-critical question is missing input; ask for the smallest sharper question instead of producing a generic review.

Question Selection

Prefer 5-10 high-signal questions for complex work. Fewer is fine when fewer questions materially affect approval. A clean gate may return only a handful of questions, or none. Stop once approval risk is well bounded; do not expand the pass into a completeness sweep across every plausible domain concern.

For multi-challenger fan-out, prefer 3-5 strongest non-duplicative questions per lane. Return more only when the assigned lens exposes genuinely separate approval risks. It is acceptable to return fewer or no questions when the lens is clear. Do not pad because sibling challenger lanes exist.

Keep a question only if all are true:

• it names a specific hidden assumption, corner case, or seam
• a different answer could change spec.md scope, acceptance semantics, ownership, failure behavior, rollout, or validation
• the orchestrator could answer it from evidence or route it to a targeted expert lane
• it is not ordinary downstream design elaboration
• it is not already handled by a sufficient lean-local inline Risk Challenge

Drop questions that only ask for best-practice coverage, implementation detail, or "more thinking" without changing approval.

When sibling lenses are provided, drop questions that primarily belong to another lane unless the point is a severity conflict or dependency the orchestrator must reconcile across lanes.

Classification

Use exactly one:

• blocks_spec_approval when spec.md cannot be honestly approved until the answer is resolved, accepted as risk, or marked as an upstream blocker
• blocks_specific_domain when approval depends on reopening one expert domain such as API, data, security, reliability, domain, QA, delivery, or architecture
• non_blocking_but_record when the point should be explicit in spec.md but does not block approval if recorded, deferred, or accepted as risk

These classification names remain stable when the skill is used as one lane in multi-challenger fan-out. Lens identifies coverage perspective only; it does not create a new severity or handoff vocabulary.

Next Action

Use exactly one:

• answer_from_existing_evidence when the orchestrator should resolve it from current repo evidence, research notes, or candidate synthesis
• targeted_research when local repository or external retrieval should answer a bounded factual gap
• expert_subagent when one read-only specialist lane should reopen a domain question using one skill
• accept_risk when the current path remains coherent and the remaining uncertainty is a conscious trade-off
• defer_to_design when the spec can be approved with an explicit constraint and the detail belongs in design/
• requires_user_decision when the question is truly external product, business, policy, or legal judgment that repo evidence and safe assumptions cannot answer

Do not use requires_user_decision for questions the orchestrator can answer from repository evidence or expert research. If used, explain why the spec should remain blocked or partially draft until the user decision exists.

Reconciliation Expectations

The orchestrator owns reconciliation after the subagent returns:

• answer each planning-critical question from evidence where possible
• for multi-lane fan-out, deduplicate sibling-lane findings and compare conflicting assumptions before recording outcomes
• reopen targeted research or one read-only expert subagent per expert question when evidence is missing
• record final resolved outcomes in existing spec.md sections, not raw subagent transcripts
• update workflow-plans/specification.md with clarification challenge status, lane or lane set used, lenses when relevant, targeted research status, resolution status, and approval or block rationale
• update workflow-plan.md with spec.md status and clarification gate status
• rerun this challenge once if material decisions changed or a major seam was reopened

Reference Loading

References are compact rubrics and example banks, not exhaustive checklists or documentation dumps. Load at most one reference by default. Load a second only when the challenge clearly spans multiple independent decision pressures, such as a thin input bundle plus a separate external-policy question.

Use references for behavior change, not reassurance. Before loading a reference, name the symptom it should correct.

| Symptom in the challenge | Load | Behavior change | | --- | --- | --- | | A hidden assumption may make approval dishonest, but the question wording is too broad or weak. | references/approval-blocker-question-examples.md | Choose a candidate-decision-specific blocker question instead of a generic checklist prompt. | | The orchestrator bundle may be too thin to challenge without guessing. | references/input-bundle-sufficiency.md | Return a missing-input blocker instead of inventing candidate decisions or validation expectations. | | A question seems important, but classification between whole-spec blocker, one-domain reopen, and record-only note is unclear. | references/domain-reopen-classification.md | Route the seam to the smallest approval-safe owner instead of doing expert analysis inside this challenge or blocking everything. | | A valid concern may belong in design/ rather than blocking spec.md review-readiness. | references/defer-to-design-vs-block-spec.md | Preserve spec-level invariants and proof obligations while deferring only stable mechanism choices. | | A question may need external product, business, support, contractual, policy, or legal judgment. | references/requires-user-decision-examples.md | Use requires_user_decision only for non-repo-answerable policy choices instead of asking the human for technical facts or inventing policy. | | A draft output is bloated, generic, answer-heavy, or too eager to approve. | references/clarification-anti-patterns.md | Prune checklist noise, design authorship, human-escalation shortcuts, and approval theater before returning. |

Do not load approval-blocker-question-examples.md and clarification-anti-patterns.md together by default: use the first to shape a blocker question, and the second to prune a draft. Do not copy an example unless the same candidate-decision seam is present.

Deliverable Shape

Return:

• Clarification Summary
• Lens
• Questions
• Reopen / Rerun Recommendation
• Confidence

For each item in Questions, include:

• Question / Hidden Assumption
• Why It Matters
• What Could Change
• Classification
• Recommended Next Action
• Evidence Or Expert Lane

Keep the wording concise and concrete. If no question survives the filter, say the clarification gate is clear and name the evidence boundary that supports that conclusion.

Stop Condition

Stop when:

• all approval-changing questions have been surfaced or the input gap is clearly blocking
• each surviving question has a classification and next action
• low-value checklist items have been pruned
• the output is short enough for the orchestrator to reconcile without reading a second spec

Anti-Patterns

• writing the answer instead of the approval question
• asking broad category questions with no candidate-decision seam
• padding to hit a quota
• treating defer_to_design as a way to hide missing spec decisions
• using requires_user_decision to avoid targeted research
• copying raw challenge output into spec.md
• turning the pass into architecture authorship, task breakdown, or approval theater
• treating every visible adjacent-domain effect as a mandatory approval question
• using formal challenge to add ceremony to bounded lean-local work when inline Risk Challenge is sufficient
• in a multi-lane fan-out, ignoring the assigned lens and producing a generic whole-spec review that duplicates sibling challengers
• treating a lens label as a question; each lane needs one concrete approval-critical question before it can produce useful output

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dankosik
• Source: Dankosik/go-service-template-rest
• License: MIT

Install and usage instructions live in the source repository linked above.