From 57b434379c555eabdb9bf64d1d54476ce80bb5a2 Mon Sep 17 00:00:00 2001
From: jgrusewski <jgrusewski@localhost>
Date: Sun, 10 May 2026 20:56:15 +0200
Subject: [PATCH] feat(claude): sp-spec-writer skill (foxhunt)

Templatizes the SP design spec format used in docs/superpowers/specs/.
Enforces pearl/feedback grounding, ISV-slot enumeration, smoke kill conditions,
sister-fix check (no-deferrals-for-complementary-fixes pearl).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../skills/foxhunt/sp-spec-writer/SKILL.md    | 101 ++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 .claude/skills/foxhunt/sp-spec-writer/SKILL.md

diff --git a/.claude/skills/foxhunt/sp-spec-writer/SKILL.md b/.claude/skills/foxhunt/sp-spec-writer/SKILL.md
new file mode 100644
index 000000000..b870cf1d7
--- /dev/null
+++ b/.claude/skills/foxhunt/sp-spec-writer/SKILL.md
@@ -0,0 +1,101 @@
+---
+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.