Skip to main content
spec-gathering Requirements gathering workflow for specification creation. Use when starting a new feature, task, or project that needs structured requirements.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/oimiragieo/agent-studio --skill spec-gatheringThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
More from this repository
name spec-gathering description Requirements gathering workflow for specification creation. Use when starting a new feature, task, or project that needs structured requirements. version 1.0.0 model sonnet invoked_by both user_invocable true tools ["Read","Write","Edit","Bash","AskUserQuestion"] best_practices ["Ask smart questions, produce structured output","Confirm understanding before proceeding","Identify services and dependencies early"] error_handling graceful streaming supported source community verified true lastVerifiedAt "2026-02-22T00:00:00.000Z" trust_score 100 provenance_sha 88ad84d796ca19ad
Requirements Gathering Skill
Overview
Gather user requirements through structured questioning and produce a validated requirements document. This skill transforms vague task descriptions into actionable, structured requirements.
Core principle: Ask smart questions, produce valid structured output. Nothing else.
When to Use
Always:
Starting a new feature or project
Clarifying ambiguous task descriptions
When user provides high-level goals without specifics
Before spec writing begins
Exceptions:
Simple bug fixes with clear reproduction steps
Single-file changes with obvious scope
User explicitly provides complete requirements
The Iron Law
NO SPEC WRITING WITHOUT VALIDATED REQUIREMENTS FIRST
Requirements must be confirmed by the user before proceeding to spec creation.
Workflow
Phase 1: Load Project Context
Understand the project structure before engaging the user.
Steps:
Read project structure files if they exist
Identify services, tech stack, and ports
Understand existing patterns and conventions
cat .claude/context/product.md 2>/dev/null || echo "No product context"
cat .claude/context/tech-stack.md 2>/dev/null || echo "No tech stack"
Phase 2: Understand the Task
If a task description was provided, confirm it:
"I understand you want to: [task description]. Is that correct? Any clarifications?"
If no task was provided, ask:
"What would you like to build or fix? Please describe the feature, bug, or change you need."
Wait for user response.
Phase 3: Determine Workflow Type
Based on the task, determine the workflow type:
If task sounds like... Workflow Type "Add feature X", "Build Y"
feature
"Migrate from X to Y", "Refactor Z" refactor
"Fix bug where X", "Debug Y" investigation
"Migrate data from X" migration
Single service, small change simple
"This sounds like a [workflow_type] task. Does that seem right?"
Phase 4: Identify Services and Scope Based on the project context and task, suggest affected areas:
"Based on your task and project structure, I think this involves:
[service1] (primary) - [why][service2] (integration) - [why]
Any other services or areas involved?"
Wait for confirmation or correction.
Phase 4.5: Invoke Context-Compressor (Progressive Disclosure Mode / ECLAIR Pattern) Before gathering requirements manually, use the context-compressor skill (progressive disclosure mode) to optimize the clarification process:
Skill ({
skill : 'context-compressor' ,
context : {
taskDescription : taskDescription,
projectContext : projectContext,
services : identifiedServices,
mode : 'progressive-disclosure' ,
},
});
Context-Compressor (progressive disclosure mode) performs:
E: Examine - Analyze ambiguities in the task descriptionC: Categorize - Prioritize by CRITICAL, HIGH, MEDIUM, LOWL: Limit - Apply 3-5 clarification capA: Assume - Apply smart defaults from project patternsI: Infer - Use existing code patterns and tech stackR: Record - Document all assumptions with [ASSUMES: X]
Prioritized clarification questions (max 5)
Smart defaults with [ASSUMES:] notation
Updated understanding of requirements
Phase 5: Gather Detailed Requirements (with Context-Compressor) Ask only the critical clarification questions identified by context-compressor:
Budget: 3-5 clarification questions maximum
Ask CRITICAL priority questions first (security, data loss, breaking changes)
Example: "Does the system need role-based access control?"
Example: "Should users be able to delete data? Is this reversible?"
Ask HIGH priority questions if budget remains (UX, architecture, scalability)
Example: "What's the expected user load?"
Example: "Should this support offline mode?"
For MEDIUM/LOW priorities, use [ASSUMES:] notation with defaults
Example: "[ASSUMES: JWT tokens with 1-hour expiry]"
Example: "[ASSUMES: REST API following existing /api/v1/ pattern]"
Collect answers and document all assumptions.
Phase 6: Confirm and Output (with Assumptions) Summarize what you understood, including clarified requirements and assumptions:
"Let me confirm I understand:
Task : [summary]
Type : [workflow_type]
Scope : [list of affected areas]
Clarified Requirements (questions asked):
✅ [Question] → [Answer]
✅ [Question] → [Answer]
✅ [Question] → [Answer]
Smart Defaults Applied (not asked due to budget or clarity):
[ASSUMES: X]
[ASSUMES: Y]
[ASSUMES: Z]
Success Criteria :
[criterion 1]
[criterion 2]
Is this correct?"
Wait for confirmation. If user objects to any assumption, allow them to override or request adjustment.
Phase 7: Map Requirements to Template Tokens (with Assumptions) After confirming requirements and assumptions with user, map gathered data to template tokens:
const tokens = {
FEATURE_NAME : gatheredRequirements.taskName ,
VERSION : '1.0.0' ,
AUTHOR : 'Claude' ,
DATE : new Date ().toISOString ().split ('T' )[0 ],
STATUS : 'draft' ,
ACCEPTANCE_CRITERIA_1 : gatheredRequirements.criteria [0 ] || '[Define acceptance criterion 1]' ,
ACCEPTANCE_CRITERIA_2 : gatheredRequirements.criteria [1 ] || '[Define acceptance criterion 2]' ,
ACCEPTANCE_CRITERIA_3 : gatheredRequirements.criteria [2 ] || '[Define acceptance criterion 3]' ,
TERM_1 : gatheredRequirements.terms ?.[0 ] || '' ,
TERM_2 : gatheredRequirements.terms ?.[1 ] || '' ,
TERM_3 : gatheredRequirements.terms ?.[2 ] || '' ,
HTTP_METHOD : gatheredRequirements.httpMethod || '' ,
ENDPOINT_PATH : gatheredRequirements.endpointPath || '' ,
PROJECT_NAME : gatheredRequirements.projectName || 'Agent Studio' ,
ASSUMPTIONS_MADE : gatheredRequirements.assumptions .map (a =>`- ${a} ` ).join ('\n' ) || '' ,
CLARIFICATIONS_ASKED : gatheredRequirements.clarifications || 0 ,
};
Validation Before Rendering:
Check all required tokens are populated (FEATURE_NAME, VERSION, AUTHOR, DATE, STATUS)
Check at least one ACCEPTANCECRITERIA * token is meaningful (not placeholder)
Verify all assumptions are documented with [ASSUMES:] notation
If missing required data, prompt user for missing information
If clarifications > 5, warn user about potential requirement incompleteness
Phase 8: Render Specification via Template Invoke the template-renderer skill to create the specification:
Skill ({
skill : 'template-renderer' ,
args : {
templateName : 'specification-template' ,
outputPath : `.claude/context/artifacts/specifications/${featureNameSlug} -spec.md` ,
tokens : tokens,
},
});
Output Location : .claude/context/artifacts/specifications/[feature-name]-spec.md
Post-Rendering Verification:
SPEC_FILE=".claude/context/artifacts/specifications/[feature-name]-spec.md"
test -f "$SPEC_FILE " && echo "✓ Spec created" || echo "✗ Spec creation failed"
grep -E '[{]{2}' "$SPEC_FILE " && echo "✗ Unresolved tokens found" || echo "✓ All tokens resolved"
YAML_COUNT=$(head -50 "$SPEC_FILE " | grep -E "^---$" | wc -l)
test "$YAML_COUNT " -eq 2 && echo "✓ YAML valid" || echo "✗ YAML invalid"
Verification Checklist Before completing requirements gathering:
Common Mistakes
Assuming Instead of Asking Why it's wrong: Assumptions lead to building the wrong thing.
Do this instead: Ask clarifying questions. Confirm understanding.
Skipping Confirmation Why it's wrong: User may have misunderstood your summary.
Do this instead: Always summarize and wait for explicit confirmation.
Vague Requirements Why it's wrong: "Make it better" is not actionable.
Do this instead: Get specific: What behavior? What outcome? How to verify?
Integration with Other Skills This skill works well with:
context-compressor : Invoked in Phase 4.5 (progressive disclosure mode) to optimize clarification process with ECLAIR pattern (3-5 limit, smart defaults, [ASSUMES:] notation)template-renderer : Used automatically after Phase 8 to render specification template with gathered requirements and assumptionsspec-critique : Use to validate the generated specificationcomplexity-assessment : Assess complexity after requirements are clearbrainstorming : Use for creative exploration before requirements gathering spec-gathering (→ context-compressor in Phase 4.5) → template-renderer → spec-critique → planner
Context-Compressor Integration Details (Progressive Disclosure Mode) :
When : Invoked at the start of Phase 5 (before manual questioning)Why : Limits clarifications to 3-5 questions (reduces cognitive load), applies smart defaults, documents all assumptionsOutput : Prioritized questions + default assumptions with [ASSUMES:] notationImpact : Specification includes documented assumptions that can be overridden during implementation
Examples
Example 1: Feature Request (End-to-End with Progressive-Disclosure & Template Rendering) Input: "Add user authentication to the app"
Confirm task: "You want to add user authentication. Is this correct?"
Invoke context-compressor in progressive disclosure mode (Phase 4.5):
Skill ({
skill : 'context-compressor' ,
context : {
taskDescription : "Add user authentication" ,
projectContext : {...},
mode : 'progressive-disclosure'
}
});
Context-compressor returns:
Identify scope: "This will touch the backend API, database, and frontend login page."
Define success criteria based on clarifications and defaults
Map to tokens:
{
FEATURE_NAME : "User Authentication" ,
VERSION : "1.0.0" ,
AUTHOR : "Claude" ,
DATE : "2026-01-28" ,
STATUS : "draft" ,
ACCEPTANCE_CRITERIA_1 : "Users can sign up with email and password" ,
ACCEPTANCE_CRITERIA_2 : "Email verification required before login" ,
ACCEPTANCE_CRITERIA_3 : "Users can reset password via email link" ,
ACCEPTANCE_CRITERIA_4 : "Role-based access control working (Admin/User/Guest)" ,
ASSUMPTIONS_MADE : "- JWT tokens with 1-hour expiry\n- bcrypt cost factor 12\n- HTTPS required" ,
CLARIFICATIONS_ASKED : 3
}
Invoke template-renderer: Skill ({
skill : 'template-renderer' ,
args : {
templateName : 'specification-template' ,
outputPath : '.claude/context/artifacts/specifications/user-authentication-spec.md' ,
tokens : tokens,
},
});
Rendered specification at .claude/context/artifacts/specifications/user-authentication-spec.md
All tokens resolved
Assumptions clearly documented with [ASSUMES:] notation
YAML frontmatter valid
Ready for spec-critique review (user can challenge any assumption)
Example 2: Bug Investigation Input: "The page loads slowly"
Clarify: "Which page specifically? What do you consider slow?"
Context: "When did this start? Any recent changes?"
Metrics: "What load time would be acceptable?"
Output: Investigation requirements with specific pages, metrics, and success criteria.
Troubleshooting
Issue: User gives one-word answers Symptoms: "Yes", "No", "That's fine" without detail.
Solution: Ask more specific questions. Provide options: "Would you prefer A, B, or C?"
Issue: Scope keeps expanding Symptoms: Every answer adds new features.
Solution: Document "Out of Scope" explicitly. Confirm: "Should we include this in this task or save for later?"
Iron Laws
NEVER begin implementation before a validated specification exists for STANDARD+ complexityALWAYS capture non-functional requirements (performance, security, scalability) explicitlyNEVER accept vague success criteria — require measurable, testable numbersALWAYS document what is explicitly out of scope, not just what is in scopeNEVER hand off to planner without explicit user confirmation of requirements
Anti-Patterns Anti-Pattern Why It Fails Correct Approach Vague requirements ("make it fast") Not measurable or testable Specify exact metrics: "P95 response time <100ms" Missing NFRs Quality attributes forgotten until too late Always capture performance, security, scalability requirements No out-of-scope section Scope creep during implementation Explicitly document what this task does NOT include Skipping user confirmation Requirements misunderstood and implemented incorrectly Confirm all requirements with the user before handoff No edge cases documented Error handling gaps discovered during QA Document empty input, bad data, timeout, and concurrent access cases
Memory Protocol Before starting:
Read .claude/context/memory/learnings.md
New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
