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:

Vague Feature Requests

• User says: "add login feature", "implement payment", "create dashboard"

• Missing: How, with what technology, what constraints?

Missing Technical Context

• No technology stack mentioned

• No integration points identified

• No performance/security constraints

Incomplete Specifications

• No acceptance criteria

• No success metrics

• No edge cases considered

• No error handling mentioned

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

Systematic Questioning

• Ask focused, specific questions

• One category at a time (2-3 questions per round)

• Build on previous answers

• Avoid overwhelming users

Quality-Driven Iteration

• Continuously assess clarity score (0-100)

• Identify gaps systematically

• Iterate until ≥ 90 points

• Document all clarification rounds

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:

• Parse and understand core requirement

• Generate feature name (kebab-case format)

• Determine document version (default 1.0 unless user specifies otherwise)

• Ensure ./docs/prds/ exists for PRD output

• 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:

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:

• Start with highest-impact gaps

• Ask 2-3 questions per round

• Build context progressively

• Use user's language

• Provide examples when helpful

Question Format:

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:

• Update clarity score

• Capture new information in the working PRD outline

• Identify remaining gaps

• If score < 90: Continue with next round of questions

• If score ≥ 90: Proceed to PRD generation

Score Update Format:

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:

• 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

{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