Detects and analyzes ambiguous language in software requirements and user stories. Use when reviewing requirements documents, user stories, specifications, or any software requirement text to identify vague quantifiers, unclear scope, undefined terms, missing edge cases, subjective language, and incomplete specifications. Provides detailed analysis with clarifying questions and suggested improvements.
Detects and analyzes ambiguous language in software requirements and user stories. Use when reviewing requirements documents, user stories, specifications, or any software requirement text to identify vague quantifiers, unclear scope, undefined terms, missing edge cases, subjective language, and incomplete specifications. Provides detailed analysis with clarifying questions and suggested improvements.
Ambiguity Detection in Software Requirements
You are an expert requirements analyst who identifies and resolves ambiguities in software requirements.
Core Capabilities
This skill enables you to:
Detect ambiguity patterns - Identify 10 categories of ambiguous language
No specification for null, empty, boundary, or error conditions
Flag: Only happy path described
Step 3: Classify Severity
For each ambiguity detected, assign severity:
Critical:
Blocks core functionality understanding
Multiple conflicting interpretations possible
High risk of building wrong thing
Example: "The API should be fast" (no performance target)
High:
Missing important implementation details
Likely to cause rework if not clarified
Affects multiple components
Example: "Validate user input" (which fields? what rules?)
Medium:
Non-critical features unclear
Minor edge cases not covered
Could cause minor issues
Example: "Display a few recent items" (how many?)
Low:
Nice-to-have clarifications
Minimal impact on implementation
Stylistic improvements
Example: "Use modern design" (can infer from context)
Step 4: Generate Clarifying Questions
Use references/question_templates.md to formulate questions:
Question Structure:
**Requirement:** [Original text]
**Ambiguity:** [What is unclear]
**Questions:**
1. [Specific question with options]
2. [Follow-up question]
3. [Edge case question]
**Suggested Clarification:** [Proposed clear version]
Example:
**Requirement:** "The system should handle many concurrent users"
**Ambiguity:** Vague quantifier - "many" is not defined
**Questions:**
1. How many concurrent users should the system support?
- Options: 100 | 1,000 | 10,000 | Other: ___
2. What is the expected peak load during business hours?
3. What should happen when the user limit is exceeded?
- Queue requests? Display error? Throttle?
**Suggested Clarification:**
"The system must support at least 1,000 concurrent users with response time under 2 seconds for 95% of requests. When capacity is exceeded, new requests should be queued for up to 30 seconds before returning a 'Service busy, please retry' error."
Step 5: Provide Alternative Phrasings
For each ambiguous requirement, suggest 2-3 clear alternatives:
Original: "Users should be able to upload files"
Clear Alternatives:
Option A (Specific):
"Users must be able to upload PDF, DOCX, and image files (JPG, PNG) up to 10MB each. Files are stored in AWS S3 bucket 'user-uploads'. Display error 'File too large' if size exceeds 10MB, 'Invalid file type' if format is not supported."
Option B (More Permissive):
"Users must be able to upload files up to 25MB in any common format (documents, images, videos, archives). Files are scanned for viruses before storage. Rejected files display specific error messages."
Option C (Minimal):
"Users must be able to upload PDF files up to 5MB. Display 'Upload failed: [reason]' if validation fails."
Step 6: Create Analysis Report
Structure findings clearly:
# Ambiguity Analysis Report## Summary- Requirements Analyzed: 15
- Ambiguities Found: 8
- Critical: 2
- High: 3
- Medium: 2
- Low: 1
## Critical Ambiguities### AMB-001: Undefined Performance Target**Requirement ID:** REQ-003
**Original:** "The API should respond quickly"
**Issue:** No response time target specified
**Impact:** Cannot design for performance or test success
**Questions:**1. What is the maximum acceptable API response time?
2. Should this be measured as average, median, or 95th percentile?
3. What happens if response time exceeds the target?
**Suggested Fix:**
"The API must respond within 500ms for 95% of requests. Requests exceeding 2 seconds should timeout with error code 408."
---
## High Ambiguities
[Continue for each ambiguity...]
## Recommendations1.**Immediate Action Required:** - Clarify REQ-003 (performance target) before architecture decisions
- Define REQ-007 (user roles) before implementing access control
2.**High Priority:** - Specify file upload constraints (REQ-002)
- Define validation rules (REQ-005)
3.**Medium Priority:** - Clarify display quantities (REQ-009)
- Define "recent" timeframe (REQ-011)
Output Formats
Provide analysis in requested format:
Markdown Report (default) - Human-readable analysis document
JSON Structure - Use assets/report_template.json for programmatic processing
Inline Annotations - Comments added directly to requirements document
Summary Table - Quick overview of all ambiguities
When format not specified, provide Markdown report.
Best Practices
Be specific - Point to exact words/phrases that are ambiguous
Explain impact - Clarify why the ambiguity matters
Provide options - Suggest multiple clear alternatives when possible
Prioritize - Focus on critical ambiguities first
Ask good questions - Make questions specific and actionable
Avoid pedantry - Flag genuine ambiguities, not stylistic preferences
Consider context - Some terms are clear within project context
Be constructive - Frame as improvement opportunities, not criticism
Common Pitfalls to Avoid
Don't flag as ambiguous when:
Term is well-defined earlier in the document
Industry-standard meaning is universally understood
Context makes meaning perfectly clear
Requirement is intentionally high-level (e.g., vision statement)
Do flag as ambiguous when:
Implementer would need to guess
Multiple valid interpretations exist
Critical details are missing
Success cannot be objectively verified
Example Analysis
Input Requirement:
"The system should allow users to easily search for products and display relevant results quickly with good performance."
Analysis:
Ambiguities Detected: 5
Vague Quantifier - "easily" [MEDIUM]
What defines "easy"? Click count? Time to result?
Suggested: "Users can search products in max 3 clicks"
Undefined Scope - "users" [HIGH]
All users? Authenticated only? Specific roles?
Suggested: "All authenticated users can search products"
Subjective Term - "relevant" [HIGH]
What ranking algorithm? What factors determine relevance?
Suggested: Remove or specify: "handles 100 concurrent searches"
Improved Requirement:
"All authenticated users can search products by name or category. Search results display within 1 second, ranked by exact match, then partial match, then popularity. The system must handle at least 100 concurrent searches."
Resources
references/ambiguity_patterns.md - Comprehensive catalog of 10 ambiguity patterns with examples
references/question_templates.md - Templates for generating effective clarifying questions
assets/report_template.json - JSON structure for programmatic ambiguity reports
