Requirements Clarity

softaworks/agent-toolkit/skills/requirements-clarity

by softaworks3027f20f3181758385a1bb8c022d4041dfb4de84No license2.5K starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 7 months ago

Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.

Instructions onlyProductivity & Workflow
AI-generated overview

Turns vague feature requests into scored, actionable PRD documents through structured clarifying dialogue.

What it does
This skill detects ambiguous feature requests and runs a structured clarification dialogue, asking two to three focused questions per round across functional scope, user interaction, technical constraints, and business value. It scores clarity on a 100-point rubric and iterates until the score reaches 90 or higher. It then writes a complete PRD to ./docs/prds/{feature_name}-v{version}-prd.md covering requirements, design decisions, acceptance criteria, and execution phases.
When to use it
Use it when requirements are unclear, a feature is complex or spans more than two days of work, or cross-team coordination is involved. It is not meant for requests that already include specific file paths, code snippets, existing function references, or clear bug reproduction steps.
Requirements
No scripts; instructions only. It requires the ability to ask the user questions interactively and a Write tool to create the PRD file, plus a writable ./docs/prds/ directory.

Requirements Clarity Skill

Description

Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.

Instructions

When invoked, detect vague requirements:

  1. Vague Feature Requests

    • User says: "add login feature", "implement payment", "create dashboard"
    • Missing: How, with what technology, what constraints?

  2. Missing Technical Context

    • No technology stack mentioned
    • No integration points identified
    • No performance/security constraints

  3. Incomplete Specifications

    • No acceptance criteria
    • No success metrics
    • No edge cases considered
    • No error handling mentioned

  4. Ambiguous Scope

    • Unclear boundaries ("user management" - what exactly?)
    • No distinction between MVP and future enhancements
    • Missing "what's NOT included"

Do NOT activate when:

  • Specific file paths mentioned (e.g., "auth.go:45")
  • Code snippets included
  • Existing functions/classes referenced
  • Bug fixes with clear reproduction steps

Core Principles

  1. Systematic Questioning

    • Ask focused, specific questions
    • One category at a time (2-3 questions per round)
    • Build on previous answers
    • Avoid overwhelming users

  2. Quality-Driven Iteration

    • Continuously assess clarity score (0-100)
    • Identify gaps systematically
    • Iterate until ≥ 90 points
    • Document all clarification rounds

  3. Actionable Output

    • Generate concrete specifications
    • Include measurable acceptance criteria
    • Provide executable phases
    • Enable direct implementation

Clarification Process

Step 1: Initial Requirement Analysis

Input: User's requirement description

Tasks:

  1. Parse and understand core requirement
  2. Generate feature name (kebab-case format)
  3. Determine document version (default 1.0 unless user specifies otherwise)
  4. Ensure ./docs/prds/ exists for PRD output
  5. Perform initial clarity assessment (0-100)

Assessment Rubric:

Functional Clarity: /30 points- Clear inputs/outputs: 10 pts- User interaction defined: 10 pts- Success criteria stated: 10 pts
Technical Specificity: /25 points- Technology stack mentioned: 8 pts- Integration points identified: 8 pts- Constraints specified: 9 pts
Implementation Completeness: /25 points- Edge cases considered: 8 pts- Error handling mentioned: 9 pts- Data validation specified: 8 pts
Business Context: /20 points- Problem statement clear: 7 pts- Target users identified: 7 pts- Success metrics defined: 6 pts

Initial Response Format:

markdown
I understand your requirement. Let me help you refine this specification.
**Current Clarity Score**: X/100
**Clear Aspects**:- [List what's clear]
**Needs Clarification**:- [List gaps]
Let me systematically clarify these points...

Step 2: Gap Analysis

Identify missing information across four dimensions:

1. Functional Scope

  • What is the core functionality?
  • What are the boundaries?
  • What is out of scope?
  • What are edge cases?

2. User Interaction

  • How do users interact?
  • What are the inputs?
  • What are the outputs?
  • What are success/failure scenarios?

3. Technical Constraints

  • Performance requirements?
  • Compatibility requirements?
  • Security considerations?
  • Scalability needs?

4. Business Value

  • What problem does this solve?
  • Who are the target users?
  • What are success metrics?
  • What is the priority?

Step 3: Interactive Clarification

Question Strategy:

  1. Start with highest-impact gaps
  2. Ask 2-3 questions per round
  3. Build context progressively
  4. Use user's language
  5. Provide examples when helpful

Question Format:

markdown
I need to clarify the following points to complete the requirements document:
1. **[Category]**: [Specific question]?   - For example: [Example if helpful]
2. **[Category]**: [Specific question]?
3. **[Category]**: [Specific question]?
Please provide your answers, and I'll continue refining the PRD.

After Each User Response:

  1. Update clarity score
  2. Capture new information in the working PRD outline
  3. Identify remaining gaps
  4. If score < 90: Continue with next round of questions
  5. If score ≥ 90: Proceed to PRD generation

Score Update Format:

markdown
Thank you for the additional information!
**Clarity Score Update**: X/100 → Y/100
**New Clarified Content**:- [Summarize new information]
**Remaining Points to Clarify**:- [List remaining gaps if score < 90]
[If score < 90: Continue with next round of questions][If score ≥ 90: "Perfect! I will now generate the complete PRD document..."]

Step 4: PRD Generation

Once clarity score ≥ 90, generate comprehensive PRD.

Output File:

  1. Final PRD: ./docs/prds/{feature_name}-v{version}-prd.md

Use the Write tool to create or update this file. Derive {version} from the document version recorded in the PRD (default 1.0).

PRD Document Structure

markdown
# {Feature Name} - Product Requirements Document (PRD)
## Requirements Description
### Background- **Business Problem**: [Describe the business problem to solve]- **Target Users**: [Target user groups]- **Value Proposition**: [Value this feature brings]
### Feature Overview- **Core Features**: [List of main features]- **Feature Boundaries**: [What is and isn't included]- **User Scenarios**: [Typical usage scenarios]
### Detailed Requirements- **Input/Output**: [Specific input/output specifications]- **User Interaction**: [User operation flow]- **Data Requirements**: [Data structures and validation rules]- **Edge Cases**: [Edge case handling]
## Design Decisions
### Technical Approach- **Architecture Choice**: [Technical architecture decisions and rationale]- **Key Components**: [List of main technical components]- **Data Storage**: [Data models and storage solutions]- **Interface Design**: [API/interface specifications]
### Constraints- **Performance Requirements**: [Response time, throughput, etc.]- **Compatibility**: [System compatibility requirements]- **Security**: [Security considerations]- **Scalability**: [Future expansion considerations]
### Risk Assessment- **Technical Risks**: [Potential technical risks and mitigation plans]- **Dependency Risks**: [External dependencies and alternatives]- **Schedule Risks**: [Timeline risks and response strategies]
## Acceptance Criteria
### Functional Acceptance- [ ] Feature 1: [Specific acceptance conditions]- [ ] Feature 2: [Specific acceptance conditions]- [ ] Feature 3: [Specific acceptance conditions]
### Quality Standards- [ ] Code Quality: [Code standards and review requirements]- [ ] Test Coverage: [Testing requirements and coverage]- [ ] Performance Metrics: [Performance test pass criteria]- [ ] Security Review: [Security review requirements]
### User Acceptance- [ ] User Experience: [UX acceptance criteria]- [ ] Documentation: [Documentation delivery requirements]- [ ] Training Materials: [If needed, training material requirements]
## Execution Phases
### Phase 1: Preparation**Goal**: Environment preparation and technical validation- [ ] Task 1: [Specific task description]- [ ] Task 2: [Specific task description]- **Deliverables**: [Phase deliverables]- **Time**: [Estimated time]
### Phase 2: Core Development**Goal**: Implement core functionality- [ ] Task 1: [Specific task description]- [ ] Task 2: [Specific task description]- **Deliverables**: [Phase deliverables]- **Time**: [Estimated time]
### Phase 3: Integration & Testing**Goal**: Integration and quality assurance- [ ] Task 1: [Specific task description]- [ ] Task 2: [Specific task description]- **Deliverables**: [Phase deliverables]- **Time**: [Estimated time]
### Phase 4: Deployment**Goal**: Release and monitoring- [ ] Task 1: [Specific task description]- [ ] Task 2: [Specific task description]- **Deliverables**: [Phase deliverables]- **Time**: [Estimated time]
---
**Document Version**: 1.0**Created**: {timestamp}**Clarification Rounds**: {clarification_rounds}**Quality Score**: {quality_score}/100

Behavioral Guidelines

DO

  • Ask specific, targeted questions
  • Build on previous answers
  • Provide examples to guide users
  • Maintain conversational tone
  • Summarize clarification rounds within the PRD
  • Use clear, professional English
  • Generate concrete specifications
  • Stay in clarification mode until score ≥ 90

DON'T

  • Ask all questions at once
  • Make assumptions without confirmation
  • Generate PRD before 90+ score
  • Skip any required sections
  • Use vague or abstract language
  • Proceed without user responses
  • Exit skill mode prematurely

Success Criteria

  • Clarity score ≥ 90/100
  • All PRD sections complete with substance
  • Acceptance criteria checklistable (using - [ ] format)
  • Execution phases actionable with concrete tasks
  • User approves final PRD
  • Ready for development handoff

Source and attribution

Source:softaworks/agent-toolkitinskills/requirements-clarityat commit3027f20

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from softaworks/agent-toolkit

React Useeffect

softaworks

Guides React developers on when to use or avoid useEffect, with alternatives for derived state, events, and data fetching.

Software Development2.5Kupdated 7 months ago

Mui

softaworks

Reference patterns for using Material-UI v7 components, sx prop styling, theming and responsive design.

Software Development2.5Kupdated 7 months ago

Jira

softaworks

Guides an agent through viewing, creating, updating and transitioning Jira issues via the jira CLI or Atlassian MCP.

Productivity & Workflow2.5Kupdated 7 months ago

Humanizer

softaworks

Edits text to remove AI-writing tells and add a more natural, human voice.

Writing & Content2.5Kupdated 7 months ago

Frontend To Backend Requirements

softaworks

Guides frontend developers in writing a backend-requirements document describing data, actions, and UI states.

Software Development2.5Kupdated 7 months ago

Excalidraw

softaworks

Delegates Excalidraw diagram file operations to subagents to avoid exhausting the main agent's context.

AI & Agents2.5Kupdated 7 months ago

More in Productivity & Workflow

Morning Note

anthropics

Featured

Drafts concise morning meeting notes on overnight developments, trade ideas and key events for coverage stocks.

Productivity & Workflow39Kupdated 2 weeks ago

Dd Meeting Prep

anthropics

Featured

Prepares question lists, benchmarks and red flags for due diligence meetings such as management presentations and expert calls.

Productivity & Workflow39Kupdated 2 weeks ago

Dd Checklist

anthropics

Featured

Builds and tracks sector-tailored due diligence checklists with workstreams, status tracking and red flag escalation.

Productivity & Workflow39Kupdated 2 weeks ago

Deal Tracker

anthropics

Featured

Tracks live M&A deals with milestones, deadlines, action items and weekly pipeline reviews.

Productivity & Workflow39Kupdated 2 weeks ago

Client Review

anthropics

Featured

Prepares client review meetings with portfolio performance, allocation analysis, talking points, and action items.

Productivity & Workflow39Kupdated 2 weeks ago

Morning Note

anthropics

Featured

Drafts concise morning meeting notes on overnight developments, trade ideas and key events for coverage stocks.

Productivity & Workflow39Kupdated 2 weeks ago