Requirements Clarity

# Requirements Clarity A systematic skill for transforming vague requirements into actionable Product Requirements Documents (PRDs) through focused dialogue and iterative clarification. ## Purpose This skill helps you avoid costly misunderstandings and rework by ensuring requirements are crystal clear before implementation begins. It uses a 100-point scoring system to systematically identify gaps and guide you through targeted questions until your requirements are development-ready. ## When to Use This Skill ### Use When - Requirements are vague or ambiguous (e.g., "add login feature", "implement payment") - Features are complex and estimated to take more than 2 days - Cross-team coordination is required - Missing technical context (no tech stack, integration points, or constraints mentioned) - Incomplete specifications (no acceptance criteria, success metrics, edge cases) - Unclear scope boundaries ("what exactly does 'user management' include?") ### Don't Use When - Specific file paths are mentioned (e.g., "fix auth.go:45") - Code snippets are already included in the request - Working with existing functions/classes (use code review instead) - Bug fixes with clear reproduction steps ## How It Works ### The Clarification Process 1. **Initial Analysis** (Step 1) - Parses your requirement description - Generates a clarity score (0-100) using a detailed rubric - Identifies what's clear and what needs clarification - Creates a feature name and prepares for PRD generation 2. **Gap Analysis** (Step 2) - Systematically identifies missing information across four dimensions: - **Functional Scope**: Core functionality, boundaries, edge cases - **User Interaction**: Inputs, outputs, success/failure scenarios - **Technical Constraints**: Performance, compatibility, security, scalability - **Business Value**: Problem statement, target users, success metrics 3. **Interactive Clarification** (Step 3) - Asks 2-3 focused questions per round (avoids overwhelming you) - Builds context progressively - Updates clarity score after each response - Continues until score reaches ≥ 90/100 4. **PRD Generation** (Step 4) - Once clarity score ≥ 90, generates comprehensive PRD - Saves to `./docs/prds/{feature-name}-v{version}-prd.md` - Includes all clarified information in structured format ### Clarity Scoring Rubric The 100-point scoring system evaluates: - **Functional Clarity** (30 points): Clear inputs/outputs, user interaction, success criteria - **Technical Specificity** (25 points): Technology stack, integration points, constraints - **Implementation Completeness** (25 points): Edge cases, error handling, data validation - **Business Context** (20 points): Problem statement, target users, success metrics ## Key Features ### Systematic Questioning - Focused, specific questions (not overwhelming) - One category at a time - Builds on previous answers - Uses your language and provides examples ### Quality-Driven Iteration - Continuous clarity assessment - Transparent score updates - Iterates until ≥ 90 points achieved - Documents all clarification rounds ### Actionable Output - Concrete specifications ready for development - Measurable acceptance criteria (checklistable format) - Executable implementation phases with specific tasks - Complete PRD with all necessary sections ### Core Principles - **Why?** (YAGNI check) - Ensures features are truly needed - **Simpler?** (KISS check) - Explores simpler alternatives before complex solutions ## Usage Examples ### Example 1: Vague Feature Request **User Input:** ``` I need a login feature for my app. ``` **Skill Response:** ``` I understand your requirement. Let me help you refine this specification. Current Clarity Score: 25/100 Clear Aspects: - Need authentication functionality Needs Clarification: - Authentication method (email/password, OAuth, SSO?) - User types and permissions - Security requirements - Integration with existing systems - Success metrics Let me systematically clarify these points... 1. Authentication Method: What authentication method do you prefer? - For example: Email/password, social login (Google/GitHub), magic links, or SSO? 2. User Management: Do you need different user roles or permissions? - For example: Admin vs. regular users, or all users have same access? 3. Technology Stack: What's your current tech stack? - For example: React frontend, Node.js backend, PostgreSQL database? ``` ### Example 2: After Clarification Round **After User Response:** ``` Thank you for the additional information! Clarity Score Update: 25/100 → 65/100 New Clarified Content: - Authentication: Email/password with optional Google OAuth - User roles: Admin and regular users with different permissions - Tech stack: Next.js 14, PostgreSQL, using NextAuth.js Remaining Points to Clarify: - Password requirements and security constraints - Session management (duration, refresh tokens?) - Edge cases (account lockout, password reset) - Success metrics (MAU, conversion rate?) Let me continue with the next round of questions... 1. Security Requirements: What are your password requirements? - For example: Minimum length, special characters, 2FA? 2. Session Management: How long should user sessions last? - For example: 24 hours, 7 days, remember me option? 3. Edge Cases: How should we handle failed login attempts? - For example: Rate limiting, account lockout after X attempts? ``` ### Example 3: Final PRD Generation **When Clarity Score ≥ 90:** ``` Perfect! I will now generate the complete PRD document... [Generates PRD at ./docs/prds/user-authentication-v1.0-prd.md] Your Product Requirements Document is ready! File: ./docs/prds/user-authentication-v1.0-prd.md Quality Score: 92/100 Clarification Rounds: 3 The PRD includes: ✓ Complete requirements description with background and value proposition ✓ Technical approach with architecture decisions ✓ Measurable acceptance criteria (functional, quality, user acceptance) ✓ 4 execution phases with specific tasks and deliverables ✓ Risk assessment and mitigation strategies You can now hand this off to your development team for implementation. ``` ## Generated PRD Structure The final PRD includes: 1. **Requirements Description** - Background (business problem, target users, value proposition) - Feature overview (core features, boundaries, user scenarios) - Detailed requirements (I/O, user interaction, data, edge cases) 2. **Design Decisions** - Technical approach (architecture, components, data storage, interfaces) - Constraints (performance, compatibility, security, scalability) - Risk assessment (technical, dependency, schedule risks) 3. **Acceptance Criteria** - Functional acceptance (feature-specific conditions) - Quality standards (code quality, test coverage, performance, security) - User acceptance (UX, documentation, training) 4. **Execution Phases** - Phase 1: Preparation (environment setup, technical validation) - Phase 2: Core Development (implement core functionality) - Phase 3: Integration & Testing (quality assurance) - Phase 4: Deployment (release and monitoring) Each phase includes specific tasks, deliverables, and time estimates. ## Output Location PRDs are saved to: ``` ./docs/prds/{feature-name}-v{version}-prd.md ``` Where: - `{feature-name}`: Auto-generated in kebab-case format - `{version}`: Document version (default 1.0, or user-specified) ## Best Practices ### DO - Answer questions thoroughly but concisely - Provide examples when you have specific preferences - Ask for clarification if questions aren't clear - Review the final PRD and provide feedback - Share constraints and non-negotiables upfront ### DON'T - Rush through clarification rounds - Assume the skill knows your technical context - Skip questions that seem "obvious" - Approve PRD before reviewing thoroughly - Provide contradictory information across rounds ## Success Criteria A successful requirements clarification session results in: - Clarity score ≥ 90/100 - All PRD sections complete with substantial content - Acceptance criteria in checklistable format - Execution phases with actionable, concrete tasks - Development team can start implementation immediately - No major questions or ambiguities remain ## Tips for Better Results 1. **Be Specific**: Instead of "fast", say "< 200ms response time" 2. **Think End-to-End**: Consider the full user journey 3. **Share Constraints Early**: Technical limitations, budget, timeline 4. **Provide Context**: Explain the "why" behind your requirement 5. **Reference Examples**: "Like Stripe's payment flow" is clearer than abstract descriptions ## Related Skills - **feature-planning**: For breaking down features after PRD is complete - **implementation-blueprint**: For detailed implementation planning - **dev-spec**: For complete design and planning sessions - **critical-brainstorm**: For exploring and stress-testing ideas before clarification --- **Need help clarifying requirements?** Invoke this skill and provide your initial requirement description. The skill will guide you through systematic clarification until you have a development-ready PRD.