skills.rest
ZaxbyHub
ZaxbyHubOFFICIAL
Explore all skills by this author →
GitHub

clarify-spec

Resolves spec clarification markers and maintains spec alignment through structured Q&A.

Updated Mar 30, 2026
Search Tags:#requirements#ambiguity resolution#requirements engineering#spec refinement#planning workflow#spec clarification
One-click install
npx skills add https://github.com/ZaxbyHub/ragappv3 --skill clarify-spec-zaxbyhub
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: clarify-spec
Source: https://github.com/ZaxbyHub/ragappv3/tree/main/.opencode/skills/clarify-spec
Command: npx skills add https://github.com/ZaxbyHub/ragappv3 --skill clarify-spec-zaxbyhub

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Ambiguous requirements with vague language and unresolved [NEEDS CLARIFICATION] markers derail planning and implementation. This Skill systematically resolves those ambiguities in an existing spec file through guided, one-at-a-time questions with recommended options. ## Core Features & Use Cases - Marker Resolution: Scans .swarm/spec.md for [NEEDS CLARIFICATION] markers and vague adjectives like "fast" or "secure" lacking measurable targets, then resolves them via structured questions. - Delta-Format Updates: Presents all spec modifications using ADDED/MODIFIED/REMOVED requirement sections and writes accepted answers back to the spec immediately. - Critic-Guarded Questioning: Consults a critic sounding board before surfacing each question, with overconfidence guards and always-surface protection for scope, security, and breaking-change topics. - Use Case: After generating a spec with open markers, invoke the clarify flow to walk through up to 8 multiple-choice questions, ending with a clarification summary and a recommendation to proceed to planning. ## Quick Start Ask the agent to clarify the open markers in the current spec by saying "clarify the spec" or invoking the /swarm clarify command.

Frequently Asked Questions about clarify-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I resolve [NEEDS CLARIFICATION] markers in a spec file?▼

Invoke the clarify flow after a spec exists in .swarm/spec.md. The protocol scans for markers and vague language, then asks one question at a time with 2-4 multiple-choice options, writing each accepted answer back to the spec immediately.

How to clarify ambiguous software requirements before planning?▼

Run the clarify-spec mode, which detects vague adjectives without measurable targets, conflicting requirements, and untestable acceptance criteria. It presents up to 8 questions per session and ends with a clarification summary recommending the next step.

Can clarify-spec create a new spec file from scratch?▼

No. CLARIFY-SPEC never creates a spec. If .swarm/spec.md does not exist, it instructs you to run the specify command first and stops. It only refines existing requirements.

What happens when the 8-question limit is reached?▼

The session stops and reports a clarification summary listing total questions asked, requirements added/modified/removed, and any remaining open ambiguities. You can start another session to continue resolving leftover items.

Which topics always require user input instead of auto-resolution?▼

Always-surface categories include scope boundaries, destructive behavior, security/privacy, backward compatibility, breaking API changes, new dependencies, deprecations, cross-platform impact, cost/performance tradeoffs, user-visible UX, rollout strategy, and QA gates.

Related Skills

Explore More Software Engineering Skills→
atholaathola
326

spec-writing

Generate structured specifications with overview, scenarios, requirements, and success criteria.

Community
Advanced
HouseGarofaloHouseGarofalo
3

speckit-workflow

Guide spec-driven development from feature specifications to dependency-ordered task lists.

Official
Advanced
RedFox-SoftRedFox-Soft
1

speckit-clarify

Identify underspecified areas in feature specs and record clarifications.

Official
Advanced
openaiopenai
5.3k

executing-plans

Executes written implementation plans with review checkpoints and verification steps.

Official
Intermediate