analysis-specifications

Reviewing Specifications

Purpose

Find gaps in specifications and generate clarifying questions that a product owner or stakeholder can answer. Focus on WHAT is missing, not HOW to implement.

Core Principle

Ask product questions, not implementation questions.

Question Format

Frame every question as a decision the user can make:

**Question**: [Clear product decision]

**Options**:
1. [Concrete choice] - [What this means for users]
2. [Concrete choice] - [What this means for users]
3. [Concrete choice] - [What this means for users]

**Why this matters**: [User or business impact]

Gap Categories

Focus on these user-facing gaps:

What to Avoid

• Implementation details (databases, APIs, protocols)
• Technical edge cases (connection failures, race conditions)
• Architecture decisions (caching, queuing, scaling)
• Performance specifications (latency, throughput)

These are valid concerns but belong in the planning phase, not specification.

Severity Classification

Output Format

## Gaps Found

### Critical
- **Gap**: [What's missing]
  - **Question**: [Product decision needed]
  - **Options**: [2-3 choices]

### Important
- **Gap**: [What's missing]
  - **Question**: [Product decision needed]
  - **Options**: [2-3 choices]

### Minor (Deferred)
- [Gap description] - can be resolved during planning

Review Process

1. Read the full specification before identifying gaps
2. Check each user story for completeness
3. Verify success criteria are measurable
4. Identify missing edge cases for each flow
5. Classify gaps by severity
6. Generate questions with concrete options
7. Group related gaps to avoid overwhelming stakeholders

Quality Checklist

Before finalizing the review, verify:

• All user stories reviewed for completeness
• Success criteria checked for measurability
• Edge cases identified for each main flow
• Gaps classified by severity (Critical/Important/Minor)
• All questions are product-focused (not technical)
• Each question has 2-3 concrete options
• "Why this matters" explains user/business impact
• Related gaps grouped together
• No implementation details in questions

Anti-Patterns to Avoid