---
name: adr
description: Legt unter docs/30-decisions/ einen neuen Architecture Decision Record an, automatisch hochnummeriert, nach festem Template (Context, Decision, Consequences, Alternatives). Ergänzt gleichzeitig den Abschnitt "Laufende ADRs" in docs/20-architecture.md.
disable-model-invocation: true
argument-hint: "<titel der entscheidung, z. b.: 'pocketbase statt supabase'>"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
---

# adr — Architecture Decision Record

## Wann der Skill läuft

Immer dann, wenn eine **Entscheidung getroffen wird, die später Kopfschmerzen
kostet, wenn sie niemand dokumentiert**. Typische Beispiele:

- Wahl einer Technologie gegen Alternativen („PocketBase statt Supabase").
- Struktur-Entscheidung, die konkurrierende Optionen hatte („Monorepo statt
  mehrerer Repos", „Events statt direktem Call").
- Betriebs-Entscheidung mit Tragweite („Caddy als Reverse-Proxy", „tägliches
  Snapshot-Backup auf Hetzner Storage Box").

**Nicht** für triviale Entscheidungen („wir benennen die Variable `user_id`
statt `uid`") — da ist der ADR mehr Last als Nutzen.

## Voraussetzungen

Existiert `docs/30-decisions/`? Wenn nicht → meldet „Kein initialisiertes
Projekt. Erst `plan-start` ausführen." Abbrechen.

## Was der Skill tut

### Schritt 1 — Titel bestimmen

- Titel kommt aus `$ARGUMENTS`. Wenn leer: freundlich nach einem Titel fragen
  (eine Zeile), nicht weiter spekulieren.
- Slug aus Titel ableiten: lowercase, Leerzeichen → Bindestrich, Sonderzeichen
  raus. Beispiel: `PocketBase statt Supabase` → `pocketbase-statt-supabase`.

### Schritt 2 — Nummer vergeben

- `ls docs/30-decisions/ | grep -E '^[0-9]{4}-'` listet bestehende ADRs.
- Höchste bestehende Nummer + 1, auf 4 Stellen gepaddet (`0001`, `0042`).
- Erste ADR → `0001`.

### Schritt 3 — Datei anlegen

- Dateiname: `docs/30-decisions/<NNNN>-<slug>.md`.
- Inhalt: aus `templates/adr.md.tmpl`, Platzhalter füllen:

| Platzhalter | Quelle |
|---|---|
| `{{ADR_NUMBER}}` | die vergebene Nummer, 4-stellig |
| `{{ADR_TITLE}}` | der Titel |
| `{{ADR_DATE}}` | `date +%F` |
| `{{ADR_AUTHOR}}` | `git config user.name`, sonst leer |

**Status** ist initial `proposed`. Der Nutzer wechselt ihn später auf
`accepted`, wenn die Entscheidung gelebt wird — oder auf
`superseded by NNNN`, wenn ein späterer ADR sie ablöst.

### Schritt 4 — Abschnitt „Laufende ADRs" in 20-architecture.md ergänzen

Am Ende von `docs/20-architecture.md` steht ein Abschnitt `## Laufende ADRs`.
Dort wird eine Zeile nach folgendem Muster angehängt:

```markdown
- [{{ADR_NUMBER}}](30-decisions/{{ADR_NUMBER}}-{{slug}}.md) — {{ADR_TITLE}} (`proposed`, {{ADR_DATE}})
```

Wenn dort noch der Platzhalter-Text `_(Noch keine ADRs. ...)_` steht: diesen
entfernen und die erste Zeile einfügen.

### Schritt 5 — Kurze Bestätigung

Dem Nutzer den neuen Pfad und die Nummer zurückmelden, und einen knappen
Hinweis: „Datei ist als `proposed` markiert. Wenn die Entscheidung steht: auf
`accepted` setzen."

## Harte Regeln

- **Nie einen bestehenden ADR überschreiben.** Nummerierung ist append-only.
- **Nie den Status eines anderen ADR ändern.** Wenn der neue ADR einen alten
  ablöst: das trägt der Nutzer selbst am alten ADR nach (im neuen ADR sollte
  er es im Header `Supersedes: NNNN` notieren — aber auch das macht der
  Nutzer, der Skill verdrahtet das nicht automatisch, weil das Fehlerquelle
  ist).
- **Keine Entscheidung erfinden.** Der Skill legt nur das Gerüst an.
  Context / Decision / Consequences füllt der Nutzer. Der Skill darf ruhig
  Vorschläge machen, wenn im Chatkontext genug Information da ist — aber er
  schreibt nichts in die Datei, was der Nutzer nicht bestätigt hat.

## Template

Siehe `./templates/adr.md.tmpl`.