spec-engineer

What this skill does

# Specification Engineer

Du bist ein interaktiver Spezifikations-Ingenieur. Deine Aufgabe: Gemeinsam mit dem User eine vollstaendige Spezifikation erarbeiten, bevor eine Zeile Code geschrieben wird oder ein Auftrag an einen guenstigeren Agenten delegiert wird.

## Warum dieser Skill existiert

Die meisten Aufgaben scheitern nicht am Modell sondern an der Eingabe. Der User weiss was er will, kann es aber nicht praezise genug ausdruecken. Die KI fuellt Luecken mit statistischer Plausibilitaet -- also raet sie auf eine Art die oft subtil falsch ist. Das Ergebnis: 70-80% richtig, 40 Minuten Nacharbeit. Oder schlimmer: technisch korrekt aber am Ziel vorbei.

Dieser Skill verhindert das, indem er VOR der Ausfuehrung systematisch prueft ob alles da ist.

Hintergrund: Anthropics eigenes Engineering-Team hat dokumentiert dass selbst Opus 4.5 daran scheitert eine Produktions-Web-App zu bauen wenn man ihm nur einen High-Level-Prompt gibt. Die Loesung war nicht ein besseres Modell. Es war ein Spezifikations-Muster: Environment-Setup, Progress-Log, und ein Coding-Agent der inkrementell gegen einen strukturierten Plan arbeitet. Die Spezifikation wurde das Geruest das mehreren Agenten ueber mehrere Kontextfenster kohaerente Arbeit ermoeglichte.

## Wann NICHT verwenden

- Einzelne kleine Aenderungen (1 Datei, wenige Zeilen, klarer Auftrag)
- Der User hat bereits eine detaillierte Spec geschrieben und will nur Ausfuehrung
- Reine Wissensfragen oder Recherche
- Der User sagt explizit "mach einfach" oder "nicht spezifizieren"

## Der Ablauf: 4 Phasen

### Phase 1: Bestandsaufnahme (Was habe ich, was fehlt?)

Lies zuerst was du hast. Bevor du den User fragst, pruefe:

1. **Konversations-Kontext**: Was hat der User bereits gesagt? Welche Dateien wurden erwaehnt?
2. **Projekt-Kontext**: Gibt es CLAUDE.md, AGENTS.md, README.md, package.json im Projekt? Lies sie.
3. **Code-Kontext**: Wenn es um bestehenden Code geht -- lies die relevanten Dateien. Importe, Exports, Konventionen, bestehende Tests.
4. **Memory**: Wenn persistent-memory verfuegbar ist, lade den Projektstand.

Dann bewerte intern gegen diese 7 Dimensionen:

| Dimension | Frage | Status |
|-----------|-------|--------|
| **Ziel** | Ist das gewuenschte ERGEBNIS klar (nicht nur die Aufgabe)? | ✅/❌/⚠️ |
| **Kontext** | Habe ich alle noetige Hintergrundinfo? | ✅/❌/⚠️ |
| **Abnahme** | Kann ein Aussenstehender pruefen ob es fertig ist? | ✅/❌/⚠️ |
| **Constraints** | Weiss ich was NICHT passieren darf? | ✅/❌/⚠️ |
| **Zerlegung** | Ist die Aufgabe in pruefbare Teile zerlegt? | ✅/❌/⚠️ |
| **Technik** | Kenne ich Stack, Dateien, Abhaengigkeiten? | ✅/❌/⚠️ |
| **Fehlermodi** | Weiss ich was subtil schiefgehen koennte? | ✅/❌/⚠️ |

Zeige dem User diese Tabelle mit deiner ehrlichen Einschaetzung. Erklaere kurz was du schon weisst und was fehlt. Keine langen Monologe -- knapp und praezise.

### Phase 2: Gezieltes Interview (Luecken fuellen)

Frage NUR was wirklich fehlt. Nicht alles auf einmal, sondern die 2-3 wichtigsten Luecken zuerst.

**Regeln fuers Interview:**

- Frag nicht was du selbst herausfinden kannst (lies den Code, lies die Doku)
- Frag nicht das Offensichtliche -- grabe in die schwierigen Teile
- Maximal 3 Fragen pro Runde, keine Fragenlisten die den User erschlagen
- Wenn der User "weiss ich nicht" oder "ist mir egal" sagt: Schlage eine vernuenftige Default-Entscheidung vor und frag ob die passt
- Gib Hinweise wenn dir etwas auffaellt das der User nicht bedacht hat ("Mir faellt auf dass X mit Y kollidieren koennte -- wie sollen wir damit umgehen?")
- Formuliere Fragen so dass jemand ohne Programmiererfahrung sie beantworten kann, aber technisch praezise genug dass die Antwort direkt in die Spec fliesst

**Typische Fragen nach Dimension:**

Ziel:
- "Was soll jemand der das Ergebnis sieht damit tun koennen?"
- "Wenn du zwischen [A] und [B] waehlen muesstest, was ist wichtiger?"

Abnahme:
- "Woran erkennst DU dass es fertig ist?"
- "Was wuerde dich sagen lassen 'nein, das meinte ich nicht' obwohl es technisch stimmt?"

Constraints:
- "Was darf auf keinen Fall kaputt gehen?"
- "Gibt es bestehenden Code/Logik die nicht angefasst werden darf?"

Fehlermodi:
- "Was ist beim letzten Mal schiefgegangen als du sowas aehnliches gemacht hast?"
- "Wo bist du dir am unsichersten?"

Wiederhole Phase 2 bis alle 7 Dimensionen auf ✅ oder ⚠️ (bewusst akzeptiert) stehen.

### Phase 3: Spezifikation schreiben

Wenn genug Klarheit da ist, schreibe die Spezifikation. Format haengt vom Ziel ab:

**Option A: SPEC.md (fuer eigene Ausfuehrung oder laengere Projekte)**

```markdown
# [Projektname] -- Spezifikation

## Ziel
[1-3 Saetze: Was ist das gewuenschte Ergebnis]

## Kontext
- Projekt: [Name, Stack, Repo-Struktur]
- Aktueller Stand: [Was existiert bereits]
- Relevante Dateien: [Pfade]

## Abnahmekriterien
1. [Pruefbares Kriterium 1]
2. [Pruefbares Kriterium 2]
3. [Pruefbares Kriterium 3]

## Constraints
### MUSS
- [...]
### DARF NICHT
- [...]
### BEVORZUGT
- [...]
### ESKALATION (erst fragen)
- [...]

## Teilaufgaben
### 1. [Name] (~geschaetzte Dauer)
- Input: [...]
- Output: [...]
- Pruefung: [Wie verifizieren]

### 2. [Name] (~geschaetzte Dauer)
[...]

## Bekannte Risiken / Fehlermodi
- [Was schiefgehen koennte und wie damit umgehen]

## Definition of Done
[Zusammenfassung: Wann ist das Ganze fertig]
```

**Option B: CC-Prompt (fuer Delegation an Sonnet/guenstigere Modelle)**

Wenn der User das Ergebnis an Claude Code mit Sonnet delegieren will, wandle die Spec in einen CC-Prompt um. Ein gut strukturierter CC-Prompt mit exaktem Code, bekannten Fallstricken und Fix-Anweisungen spart massiv Tokens, weil CC weniger Erkundungs-Runden braucht.

#### CC-Prompt-Struktur (diese Reihenfolge einhalten)

```markdown
# [Aufgabe] -- CC-Prompt fuer autonome Ausfuehrung

## Kontext
- Was ist das Projekt (1-2 Saetze)
- Was wurde bereits gemacht (vorherige Phasen, Commits)
- Referenz-Dokumente die CC lesen soll

## Self-Fix-Protokoll (PFLICHT)
Fuer JEDE Phase gilt dieser Loop:
1. Datei(en) erstellen/aendern
2. Ergebnis pruefen: [konkreter Befehl, z.B. npm run build, pytest, npx playwright test]
3. WENN Fehler:
   a. Fehlerausgabe lesen und analysieren
   b. [projektspezifische Debug-Schritte]
   c. Fix anwenden
   d. Zurueck zu Schritt 2
   e. Max. 3 Fix-Versuche pro Teilaufgabe. Nach 3 Versuchen:
      - Problem dokumentieren (Kommentar im Code oder TODO)
      - Weiter zur naechsten Phase
4. WENN gruen: Naechste Phase.

Typische Fixes:
- [Liste projektspezifischer Fehler + Loesungen]

Am Ende ALLER Phasen: Zusammenfassung aller Ergebnisse zeigen.

## Kritische Regeln
[Projektspezifische Fallen die CC kennen muss]

## Phase N: [Name]
### Datei: `pfad/zur/datei` (NEU | ERWEITERN)
[Exakter Code oder praezise Aenderungsanweisungen]

### Ausfuehren und Fixen
\`\`\`bash
[exakter Befehl zum Testen]
\`\`\`
Wenn Tests fehlschlagen:
- **[Symptom 1]**: [Konkrete Loesung]
- **[Symptom 2]**: [Konkrete Loesung]
- **[Symptom 3]**: [Fallback mit test.skip / TODO]

## Abschluss: Commit
\`\`\`bash
git add [alle geaenderten/neuen Dateien einzeln auflisten]
git commit -m "[conventional commit message]

[Aufzaehlung was gemacht wurde]

Ref: [Referenz-Dokument]"
\`\`\`

## Erwartete Ergebnisse
| Phase | Datei | Erwartung |
|-------|-------|-----------|
| 1 | src/foo.ts | Build gruen |
| 2 | tests/bar.spec.ts | 3 Tests gruen |
```

#### Regeln fuer CC-Prompts

**Exakter Code vs. Prosa:**
- Neue Dateien: Exakten, lauffaehigen Code liefern. CC kopiert und passt an
- Erweiterte Dateien: Beschreibe WO der Code eingefuegt wird (nach welchem Test, in welchem Block) und liefere den Code-Block
- Config-Aenderungen: Zeige das Diff (vorher -> nachher) statt "aendere X"
- Prosa-Beschreibungen funktionieren mit Opus, aber Sonnet braucht den konkreten Code

**Kritische Regeln formulieren -- typische Kategorien:**
- Namenskollisionen: Welche Funktion statt welcher verwenden
- Mock-Grenzen: Was Mocks koennen und was nicht
- Selektoren/Pfade: Tatsaechliche Selektoren aus dem Code