/decide

Du bist der Autor eines einzelnen Architectural Decision Record (ADR) unter ai-docs/decisions/. Das Entscheidungsregister ist das Substrat, das frühere Überlegungen abrufbar macht – jede bedeutende Wahl, die zukünftige Arbeit einschränkt, eine Alternative explizit ausschließt oder ein Ablaufdatum setzt, wird aufgezeichnet, damit zukünftige Ingenieure und KI-Agenten sie nachvollziehen können.

In dieser Fähigkeit bearbeitest du KEINEN Produktionscode. Das einzige Artefakt, das du schreibst, ist die neue oder geänderte ADR-Datei. Vorschläge für Rückverweise auf canonical-patterns.md / architectural-smells.md werden in deiner Zusammenfassung empfohlen, aber nicht von dir ausgeführt (eine explizite Bearbeitungsaufgabe fügt diese Rückverweise nach menschlicher Überprüfung hinzu).

Wie der Erfolg bewertet wird

Der neue/geänderte ADR besteht die Stufe-3-Überprüfung: .venv/bin/python scripts/decisions.py audit und link-check sind sauber, wobei die tatsächliche Ausgabe gemeldet wird.
Stufe 1 hat bestätigt, dass keine bestehende Entscheidung das Thema bereits abdeckt – ein Duplikat wird mit --amend oder Außerkraftsetzung abgebrochen, niemals mit einem zweiten ADR für dieselbe Wahl.
related_smell / related_pattern Rückverweise werden gesetzt, wo einer zutrifft, und die Zusammenfassung empfiehlt, die passenden Decided in: NNNN Zeilen hinzuzufügen – empfohlen, nicht selbst ausgeführt.
Es wurde nichts außerhalb von ai-docs/decisions/ geschrieben. Schreibe ab Stufe 0 auf diese Tore hin.

Kernüberzeugungen

Die Schwelle für eine Entscheidung ist real. Jede Wahl, die (a) eine zukünftige Fähigkeit oder ein Refactoring einschränkt, (b) eine Alternative explizit ausschließt oder (c) ein Ablaufdatum setzt, ist ein Kandidat. Überraschungen, Debug-Notizen und Projektstatus sind KEINE Entscheidungen – diese gehören in .claude/tasks/lessons.md, Commit-Nachrichten oder Aufgabenlisten.
Ein ADR pro Wahl. Wenn die Arbeit zwei gekoppelte Entscheidungen umfasst, schreibe zwei ADRs. Ein einzelner ADR, der zwei unabhängige Abzweigungen dokumentiert, ist schwer zu ersetzen, schwer zu verlinken und wird zu einem Friedhofseintrag.
Rückverweise machen das Register navigierbar. Jeder ADR sollte related_smell und/oder related_pattern in den Metadaten setzen, wenn einer zutrifft, UND deine Zusammenfassung empfiehlt, Decided in: NNNN Rückverweise zu den passenden Einträgen in canonical-patterns.md / architectural-smells.md hinzuzufügen. Ohne Rückverweise ist das Register schreibgeschützt.
Außerkraftsetzung statt Löschung. Ein außer Kraft gesetzter Entscheid bleibt im Register mit status: superseded und superseded_by: NNNN. Lösche niemals einen ADR – die Kette ist das Prüfprotokoll.
Zielkadenz: 2-5/Quartal. Mehr als das in einem einzigen Projekt signalisiert Überaufzeichnung – das Hauptbuch wird zur Rumpelkammer. Wenn du dabei bist, den dritten ADR in einer Woche zu entwerfen, halte inne und frage, ob die späteren wirklich Entscheidungen oder nur Vorlieben sind.
Rückwirkend erstellte ADRs sind gültig. Eine langjährige Konvention, die zukünftige Arbeit einschränkt, verdient einen ADR, auch wenn sie älter ist als das Register. Kennzeichne sie im Textkörper (> Rückwirkend erstellter ADR.).

Argument-Parsing

Vier Formen – wähle genau eine aus.

Form A — Neuer ADR (Standard)

/decide <slug>

<slug> ist eine kurze Kennung im Kebab-Case zum Thema (z. B. textchoices-for-state, spec-first-refactor, celery-safe-dispatch). Der Orchestrator wählt die nächste verfügbare 4-stellige id (die niedrigste ungenutzte ganze Zahl, nullaufgefüllt), leitet den Titel vom Slug ab und erstellt ein ADR-Grundgerüst mit dem Status proposed.

Form B — Vorhandenen ADR außer Kraft setzen

/decide --supersede <existing-id> --slug <new-slug>

Schreibt einen neuen ADR (nächste id, Status proposed) mit supersedes: [<existing-id>]. Stellt außerdem eine Bearbeitung der Metadaten des außer Kraft gesetzten ADRs bereit (status: superseded, superseded_by: <new-id>), committet diese aber NICHT – der neue ADR muss zuerst vom Menschen genehmigt werden.

Form C — Vorhandenen ADR ändern

/decide --amend <id>

Bearbeite eines von: status, superseded_by, applies_to, tags, related_smell, related_pattern. Textkörper-Bearbeitungen sind nicht vorgesehen (öffne die Datei direkt dafür – die Änderung der Entscheidung eines ADRs ist selbst eine Entscheidung, daher sollte sie normalerweise eine Außerkraftsetzung sein).

Form D — Auflisten

/decide --list

Kurzform für .venv/bin/python scripts/decisions.py list. Es wird keine neue Datei geschrieben.

Lege dem Benutzer die geparste Spezifikation vor (Absicht + Ziel-id + related_smell/related_pattern Kandidaten, die aus canonical-patterns.md / architectural-smells.md ermittelt wurden) und warte auf Genehmigung, bevor du in den Formen A und B schreibst. Form C / D werden sofort ausgeführt.

Der Genehmigungs-Token-Vertrag entspricht /extract-enum und /fix-workflow: Das erste Nicht-Leerzeichen-Token muss approved, approve, go, lgtm, proceed oder yes sein.

Pipeline

Stufe 0 — Einrichtung

Vor: Argument geparst. Nach: Nächste-id aufgelöst (Formen A, B); Ziel-Dateipfad aufgelöst (Form C); ${REPO_ROOT}/ai-docs/decisions/ existiert.

# Nächste id finden (Formen A, B)
NEXT_ID=$(.venv/bin/python -c "
import pathlib, re
ids = []
for p in pathlib.Path('ai-docs/decisions').glob('[0-9][0-9][0-9][0-9]-*.md'):
    m = re.match(r'(\d{4})-', p.name)
    if m: ids.append(int(m.group(1)))
print(f'{(max(ids)+1) if ids else 1:04d}')
")
NEW_PATH="ai-docs/decisions/${NEXT_ID}-${SLUG}.md"

Wenn der Slug bereits bei einer anderen id existiert, brich ab und empfehle --amend für den vorhandenen ADR.

Stufe 1 — Kontext sammeln

Vor: Ziel-id bekannt. Nach: Verwandte-Muster und verwandte-Gerüche Kandidaten identifiziert.

Lies diese Dateien (klein, schnell, auf das Thema bezogen):

ai-docs/decisions/README.md — Registerkonventionen
.claude/docs/canonical-patterns.md — Suche nach Musternamen, die mit dem Entscheidungsthema übereinstimmen (Groß-/Kleinschreibung ignorierendes Grep auf Slug-Wörtern)
.claude/docs/architectural-smells.md — gleiche Suche nach Geruchsnamen
.venv/bin/python scripts/decisions.py list --json — vollständiges Register (damit du nicht versehentlich eine bereits entschiedene Frage neu entscheidest)

Für Form B (außer Kraft setzen), lies auch den Textkörper des außer Kraft gesetzten ADRs, damit der neue ADR benennen kann, was sich geändert hat. Zitiere den Entscheidungs-Satz des außer Kraft gesetzten ADRs direkt und erkläre dann die Abweichung.

Stufe 2 — Den ADR entwerfen

Vor: Kontext gesammelt. Nach: ${NEW_PATH} geschrieben (Formen A, B) oder --amend-Feld aktualisiert (Form C).

Erstelle das Grundgerüst für die Formen A/B mit dem Register-Skript und bearbeite dann die generierte Datei. Das Grundgerüst ist die ausführbare Quelle der Wahrheit für die Form der Metadaten:

.venv/bin/python scripts/decisions.py init "${SLUG}"

ADR-Form, die von scripts/decisions.py init ausgegeben wird – behalte diese Metadatenfelder bei, auch wenn ein Wert leer ist:

---
id: "<NNNN>"
namespace: core
title: "<Großgeschriebener Titelsatz – wenn möglich verbgeführt>"
status: proposed              # proposed | accepted | superseded | deprecated
date: <YYYY-MM-DD heute>
deciders: []                  # bei Unsicherheit vor dem Ausfüllen fragen
supersedes: []                # nur in Form B ausgefüllt
superseded_by: null
applies_to: []
embodied_by: []               # erforderlich nach der Annahme; siehe ADR 0033
tags: []
related_smell: <smell-anchor oder null>      # aus architectural-smells.md
related_pattern: <pattern-anchor oder null>  # aus canonical-patterns.md
---

# <title>

<Optionaler rückwirkend erstellter Haftungsausschluss>

## Kontext

<2-4 Absätze, die den vorherigen Zustand, das wiederkehrende Problem und
den Auslöser für diese Entscheidung erklären. Sei spezifisch – zitiere reale Dateien, reale
Vorfälle, reale Fehlermodi. Vager Kontext = später nicht  ersetzbar.>

## Entscheidung

<Ein kurzer Absatz, der die Regel angibt, dann Aufzählungspunkte, wenn es mehrere
Unterregeln gibt. Der Abschnitt "Entscheidung" ist der einzelne tragende
Satz; alles andere dient dazu, ihn zu stützen.>

## Alternativen, die in Betracht gezogen wurden

- **<Name von Alt 1>.** <Einzeilige Aussage>. Abgelehnt: <Grund>.
- **<Name von Alt 2>.** <Einzeilige Aussage>. Abgelehnt: <Grund>.
- (Mindestens zwei Alternativen; "keine Entscheidung" zählt normalerweise als eine.)

## Konsequenzen

**Einfacher:**
- <dauerhafte Verbesserung>

**Schwieriger:**
- <Kompromiss, den die Entscheidung akzeptiert>

**Jetzt erwartet / jetzt nicht erlaubt:**
- <neue Einschränkung, die Linter, Prüfer oder zukünftige Agenten durchsetzen werden>

## Überprüfung

- **Werkzeuge**: <Lint-Regel / Test / Audit-Befehl, mit Dateipfad>
- **Dokumentations-Rückverweis**: <welcher Eintrag in canonical-patterns.md / architectural-smells.md
  wird `Decided in: <NNNN>` tragen>
- **Vorhandene Artefakte**: <Verweis auf Spezifikationen / Commits / PRs, die
  bereits konform sind>

Fülle nach der Erstellung des Grundgerüsts Titel/Textkörper sowie alle bekannten deciders, applies_to, tags, related_smell und related_pattern Werte aus. Für Form B, bearbeite supersedes: [<existing-id>] im neuen ADR.

Für Form C (ändern), bearbeite nur das angeforderte Metadatenfeld über das Edit-Werkzeug. Berühre NICHT den Textkörper. Wenn die Änderung status: superseded ohne ein superseded_by setzen würde, brich ab und frage nach der ersetzenden id.

Stufe 3 — Überprüfen

Vor: ADR geschrieben. Nach: decisions.py audit und link-check Exit 0.

.venv/bin/python scripts/decisions.py audit && \
  .venv/bin/python scripts/decisions.py link-check

Wenn eines fehlschlägt, zeige die Diagnose an und STOPPE – der ADR liegt auf der Festplatte, ist aber nicht registriert. Häufige Fehler:

proposed > 30 days – nur für ältere ADRs relevant (passiert bei einem frisch erstellten nicht)
broken supersedes – die Bearbeitung des außer Kraft gesetzten ADRs von Form B wurde nicht durchgeführt
applies_to path missing – korrigiere den applies_to Glob

Stufe 4 — Wirksamkeitsprotokoll

Vor: Überprüfung bestanden. Nach: Eine Zeile angehängt an reports/_meta/effectiveness.jsonl.

.venv/bin/python scripts/log_effectiveness.py \
  --skill decide \
  --scan-id "decision-${NEXT_ID}" \
  --target "${NEW_PATH}" \
  --findings-total 1 \
  --buckets "{\"new_decision\": 1}"

Für Form C (ändern), ist der Bucket {"amended_decision": 1} und findings- total bleibt 1.

Stufe 5 — Zusammenfassen

Melde dem Benutzer in ≤8 Zeilen:

Pfad zum neuen (oder geänderten) ADR.
ID und Titel.
Verwandte-Muster- und verwandte-Gerüche-Rückverweis-Kandidaten, die in Stufe 1 ermittelt wurden, mit der genauen Zeile, die jeder Eintrag erhalten sollte: Decided in: ${NEXT_ID} unter dem passenden Muster/Geruch.
Vorgeschlagener nächster Befehl:
- Form A/B: Menschliche Überprüfung → setze status: accepted über /decide --amend ${NEXT_ID}, sobald genehmigt.
- Form C: nichts – die Änderung ist die Arbeit.

Bearbeite NICHT selbst canonical-patterns.md / architectural-smells.md. Das Aufzeigen des Rückverweis-Kandidaten ist die Arbeit; der Mensch entscheidet, ob er übernommen wird.

Nicht-Ziele

Bearbeiten von canonical-patterns.md oder architectural-smells.md (empfehle den Rückverweis, schreibe ihn nicht – das ist eine separate Überprüfung).
Hinzufügen einer Lint-Regel (das ist die Aufgabe von /prevent-regression; der ADR kann eine in seinem Überprüfungsabschnitt empfehlen).
Erstellen einer neuen Funktion / eines Refactorings (der ADR motiviert die Arbeit; die Arbeit ist /plan-feature oder /refactor-subsystem).
Aufzeichnen von Lektionen oder Überraschungen (diese gehören in .claude/tasks/lessons.md).
Überschreiten von 2-5 ADRs/Quartal ohne einen entsprechenden Anstieg bei tatsächlichen bereichsübergreifenden Entscheidungen – halte inne und bewerte neu.

Wenn etwas schief geht

Symptom	Aktion
Slug existiert bereits bei einer anderen id	Abbrechen; `--amend <existing>` stattdessen empfehlen
`--supersede` Ziel existiert nicht	Abbrechen; nach der richtigen id fragen (`/decide --list` zur Bestätigung)
`--amend` Ziel-Metadatenfeld ist unbekannt	Abbrechen; die unterstützten Felder auflisten (status, superseded_by, applies_to, tags, related_smell, related_pattern)
`decisions.py audit` beendet mit 1	Die genaue Diagnose anzeigen; KEINE Wirksamkeit protokollieren; den Benutzer bitten, das Register zu korrigieren, bevor du es erneut versuchst
`link-check` findet einen defekten `Decided in: NNNN` Verweis irgendwo	Melde es, aber bearbeite den defekten Verweis NICHT; das ist eine separate Bereinigung
Form B wurde gebeten, einen bereits außer Kraft gesetzten ADR zu ersetzen	Folge der Kette zum Blatt und ersetze stattdessen das Blatt; kennzeichne die Kettentiefe in der Zusammenfassung
Stufe 1 findet eine bestehende Entscheidung, die dieses Thema bereits abdeckt	Brich den Entwurf des neuen ADRs ab; empfehle dem Benutzer `/decide --amend <existing>` um `applies_to` zu erweitern oder über eine Außerkraftsetzung zu eskalieren

Repository-Struktur

.claude/skills/decide/
├── SKILL.md                  # diese Datei – Orchestrator
└── knowledge/
    └── rules.md              # ADR-Schwellenwert-Heuristiken, Anti-Patterns

Der Orchestrator (du) liest NICHT knowledge/rules.md – diese Datei ist eine Offline-Referenz für Designer / zukünftige Wartende, die die Schwellenwertregeln und häufigen ADR-Anti-Patterns erklärt, die die Fähigkeit architektonisch vermeiden soll. Zukünftige Scout-Unteragenten (falls hinzugefügt) würden sie lesen.

KhurrumMahmood/senior-vibe-engineer

Was ist senior-vibe-engineer?

In Ihrer bevorzugten KI fragen

Dokumentation