# Requirements Clarity > - Skill: `frank-luongt/requirements-clarity` (Agent Skill) - Install (CLI): `npx skillmds@latest add frank-luongt/requirements-clarity` - Raw SKILL.md: https://api.skillmd.com/api/skills/frank-luongt/requirements-clarity/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: frank-luongt (https://skillmd.com/u/frank-luongt) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/frank-luongt/requirements-clarity --- --- name: requirements-clarity description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days of work), or involve cross-team coordination. Applies a 100-point scoring system across 4 dimensions (functional clarity, technical specificity, implementation completeness, business context) to systematically transform vague requests into actionable PRDs. tags: [requirements, prd, clarity, planning] --- # Requirements Clarity Transform vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system. ## When to Use - "Add login feature" -- missing: how, what technology, what constraints - "Implement payment" -- missing: provider, flow, error handling - "Create dashboard" -- missing: what data, for whom, what decisions - Any feature request missing acceptance criteria, success metrics, or edge cases - Complex features (>2 days estimated work) - Cross-team coordination needed ## When NOT to Use - Specific file paths mentioned ("fix auth.go:45") - Code snippets included - Bug fixes with clear reproduction steps - Simple, well-defined tasks ## Two Core Questions Before any implementation, ask: 1. **Why?** (YAGNI check) -- Is this actually needed? What problem does it solve? 2. **Simpler?** (KISS check) -- Is there a simpler way to achieve the same goal? ## Scoring System (100 points) ### Functional Clarity (30 pts) | Criterion | Points | |---|---| | Clear inputs/outputs defined | 10 | | User interaction flow described | 10 | | Success criteria stated | 10 | ### Technical Specificity (25 pts) | Criterion | Points | |---|---| | Technology stack mentioned | 8 | | Integration points identified | 8 | | Constraints specified (performance, security, scale) | 9 | ### Implementation Completeness (25 pts) | Criterion | Points | |---|---| | Edge cases considered | 8 | | Error handling mentioned | 9 | | Data validation specified | 8 | ### Business Context (20 pts) | Criterion | Points | |---|---| | Problem statement clear | 7 | | Target users identified | 7 | | Success metrics defined | 6 | ## Process ### Step 1: Initial Assessment Parse the requirement and score it: ```markdown **Current Clarity Score**: X/100 **Clear Aspects**: - [List what's already clear] **Needs Clarification**: - [List gaps by dimension] ``` ### Step 2: Gap Analysis Identify missing information across 4 dimensions: **Functional Scope**: What is the core functionality? What are the boundaries? What is out of scope? What are edge cases? **User Interaction**: How do users interact? What are the inputs/outputs? What are success/failure scenarios? **Technical Constraints**: Performance requirements? Compatibility? Security considerations? Scalability needs? **Business Value**: What problem does this solve? Who are the target users? What are success metrics? What is the priority? ### Step 3: Interactive Clarification Ask 2-3 focused questions per round, starting with highest-impact gaps: ```markdown I need to clarify the following: 1. **[Category]**: [Specific question]? - For example: [Example if helpful] 2. **[Category]**: [Specific question]? ``` After each response, update the score: ```markdown **Clarity Score Update**: X/100 -> Y/100 **Remaining gaps**: - [List if score < 90] ``` Continue until score >= 90. ### Step 4: PRD Generation Once clarity score >= 90, generate a structured PRD: ```markdown # {Feature Name} - PRD ## Background - **Business Problem**: [What problem this solves] - **Target Users**: [Who uses this] - **Value Proposition**: [Why it matters] ## Requirements - **Core Features**: [What it does] - **Boundaries**: [What's in/out of scope] - **User Scenarios**: [How users interact] - **Edge Cases**: [Boundary conditions] ## Technical Approach - **Architecture**: [Key decisions and rationale] - **Components**: [Main technical components] - **Constraints**: [Performance, security, scale] ## Acceptance Criteria - [ ] [Specific, testable criterion] - [ ] [Specific, testable criterion] - [ ] [Specific, testable criterion] ## Execution Phases ### Phase 1: [Name] - [ ] [Task with deliverable] - [ ] [Task with deliverable] ### Phase 2: [Name] - [ ] [Task with deliverable] ## Risk Assessment | Risk | Impact | Mitigation | |---|---|---| | [Description] | High/Med/Low | [Plan] | --- **Clarity Score**: {score}/100 **Clarification Rounds**: {rounds} ``` ## Guidelines ### DO - Ask specific, targeted questions (not open-ended) - Build on previous answers - Provide examples to guide users - Summarize what you've learned each round - Stay in clarification mode until score >= 90 - Generate concrete, testable acceptance criteria ### DON'T - Ask all questions at once (overwhelming) - Make assumptions without confirmation - Generate PRD before reaching 90+ score - Use vague or abstract language in the PRD - Skip any required sections - Accept "it should just work" as a requirement ## Anti-Patterns | Avoid | Why | Instead | |---|---|---| | Starting to code with vague requirements | Rework, wasted effort | Clarify first, code second | | Accepting "make it nice" | Not testable | Define specific visual criteria | | Skipping edge cases | Production bugs | Ask "what if X fails/is empty/is huge?" | | No success metrics | Can't measure completion | Define measurable outcomes | | Scope creep during clarification | Never reaches 90 | Separate MVP from future enhancements | ## References - Based on [softaworks/agent-toolkit requirements-clarity](https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity) (MIT License)