evolve

# Spec Evolution and Reconciliation

## Overview

Handle spec/code mismatches through AI-guided analysis and user-controlled evolution.

Specs WILL diverge from code. This is normal and healthy. The question is: which should change?

This skill detects divergence, analyzes the mismatch, recommends resolution, and executes the change.

## When to Use

**Use this skill when:**
- Code review detects spec/code mismatch
- Verification finds spec compliance issues
- Developer explicitly requests evolution
- Implementation reveals better approach than spec
- Spec ambiguity discovered during implementation

**Auto-triggered by:**
- `sdd:review-code` (when deviations found)
- `sdd:verification-before-completion` (when compliance fails)

**Don't use this skill when:**
- No mismatch exists (everything compliant)
- Spec doesn't exist yet → Use `sdd:spec`
- Multiple specs need consolidation → Use `sdd:spec-refactoring`

## Prerequisites

Ensure spec-kit is initialized:

{Skill: spec-kit}

If spec-kit prompts for restart, pause this workflow and resume after restart.

## The Process

### 1. Detect Mismatches

**Identify all spec/code divergences:**

```bash
# Read spec
cat specs/features/[feature-name].md

# Compare to implementation
# For each requirement in spec:
#   - What does spec say?
#   - What does code do?
#   - Do they match?
```

**Categorize each mismatch:**
- **Missing in code**: Spec requires it, code doesn't have it
- **Extra in code**: Code implements it, spec doesn't mention it
- **Different behavior**: Spec says X, code does Y
- **Ambiguous spec**: Spec unclear, code made assumption

**Document all mismatches with:**
- Spec requirement (quote from spec)
- Actual implementation (what code does)
- Location (file:line in code, section in spec)

### 2. Analyze Each Mismatch

**For each mismatch, determine:**

**Type:**
- Architectural (affects system design)
- Behavioral (changes functionality)
- Cosmetic (naming, organization, details)

**Severity:**
- **Critical**