ambiguity-detector

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

1. **Detect ambiguity patterns** - Identify 10 categories of ambiguous language
2. **Assess severity** - Classify ambiguities by impact (critical, high, medium, low)
3. **Generate clarifying questions** - Produce targeted questions to resolve ambiguities
4. **Suggest improvements** - Provide clear, testable alternatives
5. **Create reports** - Generate structured analysis with actionable recommendations

## Analysis Workflow

Follow this process when analyzing requirements for ambiguity:

### Step 1: Read Requirements Thoroughly

Read each requirement statement and identify:
- Core intent and purpose
- Actors and entities involved
- Actions and behaviors described
- Constraints and conditions
- Success criteria

### Step 2: Scan for Ambiguity Patterns

Use `references/ambiguity_patterns.md` to systematically check for:

**1. Vague Quantifiers**
- Words: "many", "few", "some", "several", "enough", "reasonable"
- Flag: Any imprecise quantity without numeric specification

**2. Temporal Ambiguity**
- Words: "soon", "quickly", "frequently", "immediately", "real-time"
- Flag: Timing without specific duration or frequency

**3. Unclear Scope**
- Words: "all", "the system", "etc.", "relevant", "applicable"
- Flag: Undefined boundaries or extent

**4. Weak Verbs/Conditionals**
- Words: "might", "could", "should", "if possible", "where appropriate"
- Flag: Unclear obligation level or unspecified conditions

**5. Undefined Terms**
- Acronyms, jargon, technical terms without definition
- Flag: Domain-specific terminology that needs clarification

**6. Incomplete Specifications**
- Missing error handling, validation rules, constraints
- Flag: No mention of edge cases or failure scenarios

**7. Subjective Language**
- Words: "user-friendly", "fast", "modern", "intuitive", "clean"
- Flag: Qualitative descriptions without measurable criteria

**8. Implicit Assumptions**
- Words: "obviously", "of course", "as usual", "standard"
- Flag: Unstated dependencies or assumed context

**9. Unclear References**
- Words: "it", "this", "that", "they", "same"
- Flag: Pronouns with ambiguous antecedents

**10. Missing Edge Cases**
- 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:

```markdown
# 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...]

## Recommendations

1. **Immediate Action Requir