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>
This commit is contained in:
jgrusewski
2026-05-10 20:56:15 +02:00
parent 7cf07875e7
commit 57b434379c

View File

@@ -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.