---
name: sp-spec-writer
description: Produces a foxhunt SP design spec at docs/superpowers/specs/YYYY-MM-DD-spXX-<topic>-design.md following the established format — Problem, Pearl/feedback grounding, Approach, Phases A/B/C, ISV slots required, Smoke gate, Anti-patterns avoided, Pearl-distill hook. Use when starting a new sprint plan or revising one.
---

# Foxhunt SP Spec Writer

Templatizes the SP design spec format. Reuses the canonical structure from prior specs in `docs/superpowers/specs/`.

## When to invoke

- "Write SP spec for <topic>".
- "Start SP-N spec".

## Inputs you must collect first

Ask the user (one at a time):

1. **SP number**. Look at `docs/superpowers/specs/` and propose the next free integer.
2. **Topic** (short slug, kebab-case).
3. **Problem statement** — one paragraph. Symptoms or metrics required.
4. **Pearl/feedback grounding** — which memory files motivate this work? At least one required (per `feedback_isv_for_adaptive_bounds.md` etc.).
5. **Sister-fix check** (`pearl_no_deferrals_for_complementary_fixes.md`). Ask: "Is there a complementary fix that should ride along in this spec?" If yes, integrate; if no, document why.

## Spec template

Render a new file at `docs/superpowers/specs/YYYY-MM-DD-spN-<topic>-design.md` with:

```markdown
# SP-N: <Topic>

| | |
|---|---|
| **Date** | <today YYYY-MM-DD> |
| **Author** | <user> |
| **SP** | N |
| **Branch** | sp<N>-<topic> |

## 1. Problem

<One paragraph; symptoms, metrics, or repro.>

## 2. Pearl/feedback grounding

- `<memory_file_1.md>` — <one sentence>
- `<memory_file_2.md>` — <one sentence>

## 3. Approach

<Root-cause framing. Why this fix, not another.>

## 4. Phases

### Phase A — <name>
- A.1 <step>
- A.2 <step>
…

### Phase B — <name>
- B.1 <step>
…

### Phase C (smoke + close-out)
- C.1 Smoke launch (`scripts/argo-train.sh ...`)
- C.2 Smoke gate: <kill conditions>
- C.3 Close-out doc + pearl distillation

## 5. ISV slots required

| Slot index | Name | Purpose | Source pearl |
|---|---|---|---|
| <S> | <NAME> | <purpose> | <pearl> |

`ISV_TOTAL_DIM` bump: OLD → NEW.

## 6. Smoke gate

| Anomaly | Detection | Action |
|---|---|---|
| <e.g., NaN loss> | <log signal> | kill within <K> steps |

## 7. Anti-patterns avoided

- <which feedback rules this spec is honoring; e.g., feedback_no_stubs.md, feedback_isv_for_adaptive_bounds.md>

## 8. Pearl-distill hook

After close-out, distill a pearl for: <expected pattern>.
```

## Discipline enforced by this skill

- The spec MUST cite at least one memory file in §2.
- The spec MUST list ISV slots in §5 (or explicitly state "no new slots needed").
- The spec MUST list smoke kill conditions in §6 (or explicitly state "no smoke required").
- The spec MUST list which `feedback_*.md` rules it honors in §7.
- Sister-fix check is mandatory; the user must answer the question.

## After writing

Suggest invoking `foxhunt-sp-critical-reviewer` for the v2 critical-review pass before promoting the spec to plan.
