spec-refactoring

# Specification Refactoring

## Overview

Refactor specifications that have grown organically to improve clarity, consistency, and maintainability.

As specs evolve through `sdd:evolve`, they can accumulate:
- Inconsistencies
- Redundancies
- Unclear sections
- Poor organization

This skill consolidates and improves specs while ensuring all implemented features remain covered.

## When to Use

- Spec has evolved significantly through multiple updates
- Multiple related specs have redundancy
- Spec is difficult to understand or implement from
- Before major feature work on legacy spec
- Periodic maintenance (quarterly review)

**Warning:** Never refactor specs during active implementation. Wait until stable.

## The Process

### 1. Analyze Current State

**Read all related specs:**
```bash
# Single spec
cat specs/features/[feature].md

# Multiple related specs
cat specs/features/user-*.md
```

**Document current issues:**
- Inconsistencies (conflicting requirements)
- Redundancies (duplicate requirements)
- Unclear sections (ambiguities)
- Poor structure (hard to navigate)
- Outdated sections (no longer relevant)

### 2. Review Implementation

**Check what's actually implemented:**
```bash
# Find implementation
rg "[feature-related-terms]" src/

# Check tests
rg "[feature-related-terms]" tests/
```

**Critical:** Refactored spec MUST cover all implemented features.

**Create coverage map:**
```
Implemented Feature 1 → Spec Requirement X
Implemented Feature 2 → Spec Requirement Y
...
```

If implementation exists without spec coverage, ADD it during refactor.

### 3. Identify Consolidation Opportunities

**Look for:**

**Redundant requirements:**
- Same requirement stated multiple times
- Similar requirements that could merge
- Duplicate error handling

**Inconsistent terminology:**
- Same concept called different names
- Inconsistent capitalization
- Different formats for similar things

**Scattered related requirements:**
- Auth requirements in multiple places
- Err