Refining Specifications

---
name: refining-specifications
description: Improves specification quality through completeness checks, clarity verification, and structured feedback. Use when specifications lack detail, have ambiguities, or need quality improvement.
---

# Refining Specifications

## Execution Steps

1. Load the current spec file
2. Perform structured ambiguity & coverage scan using taxonomy below
3. For each category, mark status: **Clear / Partial / Missing**
4. Produce internal coverage map used for prioritization (do not output raw map unless no questions will be asked)

## Taxonomy for Ambiguity & Coverage Scan

### Functional Scope & Behavior

- Core user goals & success criteria
- Explicit out-of-scope declarations
- User roles / personas differentiation

### Domain & Data Model

- Entities, attributes, relationships
- Identity & uniqueness rules
- Lifecycle/state transitions
- Data volume / scale assumptions

### Interaction & UX Flow

- Critical user journeys / sequences
- Error/empty/loading states
- Accessibility or localization notes

### Non-Functional Quality Attributes

- Performance (latency, throughput targets)
- Scalability (horizontal/vertical, limits)
- Reliability & availability (uptime, recovery expectations)
- Observability (logging, metrics, tracing signals)
- Security & privacy (authN/Z, data protection, threat assumptions)
- Compliance / regulatory constraints (if any)

### Integration & External Dependencies

- External services/APIs and failure modes
- Data import/export formats
- Protocol/versioning assumptions

### Edge Cases & Failure Handling

- Negative scenarios
- Rate limiting / throttling
- Conflict resolution (e.g., concurrent edits)

### Constraints & Tradeoffs

- Technical constraints (language, storage, hosting)
- Explicit tradeoffs or rejected alternatives

### Terminology & Consistency

- Canonical glossary terms
- Avoided synonyms / deprecated terms

### Completion Signals

- Acceptance criteria testability
- Measurable Definition of Done style indicators

### Misc / Placeholders

- TODO markers / unresolved decisions
- Ambiguous adjectives ("robust", "intuitive") lacking quantification

## Question Generation Guidelines

For each category with **Partial** or **Missing** status, add a candidate question opportunity unless:

- Clarification would not materially change implementation or validation strategy
- Information is better deferred to the planning phase (note internally)

### Question Prioritization

Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Apply these constraints:

- Maximum of 5 total questions across the whole session
- Each question must be answerable with EITHER:
  - A short multiple-choice selection (2–5 distinct, mutually exclusive options), OR
  - A one-word / short-phrase answer (explicitly constrain: "Answer in <=5 words")
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation
- Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness)
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests
- If more than 5 categories remain unresolved, select the top 5 by an **Impact × Uncertainty** heuristic

## Output Format

Add your questions to a new section at the bottom of the spec titled "Open Questions for Clarification".

Update the specification file with:

```markdown
## Open Questions for Clarification

### Question 1: [Category - Brief Topic]
**Question**: [Clear, specific question]
**Options** (if multiple choice):
- A: [Option description]
- B: [Option description]
- C: [Option description]

**Impact**: [Why this matters for implementation]

---

### Question 2: [Category - Brief Topic]
**Question**: [Clear, specific question (answer in <=5 words)]

**Impact**: [Why this matters]

---

[... up to 5 questions total]
```

## Integration with Workflow

### Natural Progression

1. `writing-specifications` - Create initial spec
2. **`refining-specifications`** - Detect and resolve ambiguity
3. `writing-plans` - Create detailed implementation plan
4. Execute implementation

### When to Use

**After spec creation**: Run refinement to catch gaps before planning
**Before implementation**: Ensure all decisions are clear
**After feedback**: Incorporate stakeholder input and re-check for gaps

## Use Cases

### Ambiguous Requirements
**User**: "Review the auth spec for gaps"
**You**: Scan taxonomy, identify missing error handling approach, unclear session timeout, ambiguous "secure" requirement, generate 3-5 questions

### Pre-Planning Review
**User**: "Is this spec ready for planning?"
**You**: Check completeness across taxonomy, identify missing acceptance criteria, unclear performance requirements, add questions section

### Post-Feedback Refinement
**User**: "We got feedback on the spec, check for new gaps"
**You**: Re-scan with new information, identify areas still ambiguous, prioritize remaining questions

## Quality Criteria

A good refinement session:

✅ Identifies genuine ambiguities that would cause implementation confusion
✅ Asks questions that materially impact design decisions
✅ Prioritizes high-impact uncertainties
✅ Limits questions to 5 most critical
✅ Makes questions easy to answer (multiple choice or short phrase)
✅ Focuses on what can't be deferred to planning phase

## Related Skills

- `writing-specifications` - Create specifications (use before refinement)
- `validating-roadmaps` - Check consistency across multiple specs (use for projects with many specs)
- `writing-plans` - Create implementation plans (use after refinement)