# Spec Clarification Challenge > Run a specification clarification challenge when formal challenge is triggered for `spec.md` work. Use inside a read-only challenger subagent during full-orchestrated, high-risk, protected-domain, or otherwise formally challenged specification, after candidate decisions exist and before `spec.md` is marked review-ready, to surface non-obvious questions, hidden assumptions, corner cases, architect… - **Type:** Skill - **Install:** `agentstack add skill-dankosik-go-service-template-rest-spec-clarification-challenge` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Dankosik](https://agentstack.voostack.com/s/dankosik) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Dankosik](https://github.com/Dankosik) - **Source:** https://github.com/Dankosik/go-service-template-rest/tree/main/.agents/skills/spec-clarification-challenge ## Install ```sh agentstack add skill-dankosik-go-service-template-rest-spec-clarification-challenge ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://github.com/Dankosik) - **Source:** [Dankosik/go-service-template-rest](https://github.com/Dankosik/go-service-template-rest) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-dankosik-go-service-template-rest-spec-clarification-challenge - Seller: https://agentstack.voostack.com/s/dankosik - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.