spec-refine

# Spec Refine - Iterative Specification Refinement

You are orchestrating an iterative specification refinement workflow for the feature: **$ARGUMENTS**

## Parse Arguments

Extract from `$ARGUMENTS`:
- `feature_name`: The feature being specified (required, first positional argument)
- `--human-only`: Skip automated phases, go directly to human review
- `--verbose`: Show detailed search and decision information
- `--include-docs`: Include docs/, README files in research scope

If no feature name provided, use AskUserQuestion to request it.

## Workflow Overview

```
PHASE 1: what-auto   → Automated requirements refinement (2-5 iterations)
PHASE 2: what-human  → Human review of requirements spec
PHASE 3: how-auto    → Automated implementation planning (2-5 iterations)
PHASE 4: how-human   → Human review of implementation spec
PHASE 5: tickets     → Generate implementation tickets
```

## Step 1: Check for Existing Spec

Look for existing spec at: `docs/specs/{feature_name}/spec.md`

**If exists**: Read the YAML frontmatter to determine current state:
- Extract `phase`, `iteration`, and `convergence` metrics
- Resume from current phase/iteration
- Report: "Resuming {feature_name} from {phase}, iteration {iteration}"

**If not exists**: Proceed to Step 2 (seeding)

## Step 2: Seed Initial Spec (New Features Only)

Invoke the seed-spec skill to gather requirements and generate initial spec:

```
Use skill: seed-spec
Arguments: {feature_name}
```

This will:
1. Ask clarifying questions about the feature via AskUserQuestion
2. Generate initial spec.md from template
3. Create docs/specs/{feature_name}/ directory

## Step 3: Execute Current Phase

### Phase: what-auto or how-auto (Automated Refinement)

For each iteration (min 2, max 5):

1. **Analyze**: Invoke analyze-ambiguities skill (context: fork)
   - Input: Current spec document
   - Output: List of ambiguities, gaps, unclear items

2. **Research**: Invoke research-codebase skill (context: fork)
   - Input: Ambiguity