Stage

Übersicht

Stage ist ein verbindendes Dokument für einen Engineering-Änderungszyklus – es ersetzt nicht die Ergebnisse einzelner Skills, sondern hält fest, was jeder Skill hervorgebracht hat, wie diese Ergebnisse zueinander in Beziehung stehen und die vollständige Geschichte dieser Änderungsrunde.

Stage beantwortet vier Fragen:

Was wollten wir ursprünglich tun? (MISSION + Soil-Dokumente)
Wie wurde die Implementierung sicher delegiert? (Task-Contract-Vorwärtsverweisungen)
Was haben wir tatsächlich erreicht? (Ist-Dokumente + ADR)
Warum gibt es Abweichungen? (Soil vs. Ist-Differenzen + Lernzusammenfassung)

                          STAGE.md
                   (Verbindungsebene / Index + Erzählung)
                          │
    ┌────────┬────────┬────┴────┬────────────┬────────┬────────┐
    │        │             │    │            │        │        │
  MISSION   Soil-Dokumente  Umsetzungsplan  Task-Contract Ist-Dokumente  Validierung
  (Ziel)    (Design)        (plan+todo)      (Delegations-  (Ergebnisse)  (Nachweise)
                                              grenzen)
                                                │
                                              ADR
                                      (Pflicht, mindestens ein Eintrag pro Stage)

Wann verwenden

Die Erstellung eines Stages wird vollständig vom Benutzer bestimmt. Es wird nur auf explizite Anfrage des Benutzers erstellt, es gibt keine automatischen Auslöser.

Der Benutzer initiiert normalerweise auf folgende Weise:

„Stage erstellen“ / „Ein Stage beginnen“
„Stage für diese Runde anlegen“
„Stage abschließen“ / „Stage versiegeln“
Nach /plan-Ausgabe antwortet der Benutzer auf die Frage „Ist ein Stage-Dokument erforderlich?“ mit „Ja“

Typische Anwendungsszenarien (als Referenz für den Benutzer, keine Auslöseregeln):

Änderungen, die mehrere Aufgaben umfassen und eine logische Einheit bilden
Neue Funktionen über mehrere Module hinweg
Refactoring, das die interne Struktur ändert, das Verhalten aber unverändert lässt
Vollständige Reparaturkette für einen Produktionsfehler
Jede Änderung, bei der eine Architekturentscheidung dokumentiert werden muss

Keine automatischen Auslöser:

Einzelne isolierte Aufgaben oder mechanische Änderungen erstellen nicht automatisch ein Stage
Reine Dokumentationsaktualisierungen erstellen nicht automatisch ein Stage
Der Agent entscheidet nicht eigenständig basierend auf der Anzahl der Aufgaben oder dem modulübergreifenden Umfang – der Benutzer muss bestätigen

Auch wenn delegated-task-contract das zugehörige Stage benötigt, darf die Stage-Erstellung nicht automatisch ausgelöst werden; falls noch kein Stage existiert, muss es anhalten und den Benutzer um eine explizite Entscheidung bitten. Verzeichniszuordnung, einseitige Indizierung, Statusabgleich und Sperrmechanismen folgen einheitlich den Regeln zur Integration von Stage und Task-Contract.

Stage-Typen

Typ	Motivation	Erfolgskriterium	Soil vs. Ist	Dokumentschwerpunkt
feat	Neue Fähigkeit hinzufügen	Neues Verhalten tritt auf und entspricht der Spezifikation	Abweichungen sind normal, müssen dokumentiert werden	spez + api-contract + api-doc
opt	Vorhandenes Verhalten verbessern	Metriken erreichen Zielwerte	Kurze Dokumentation der Optimierungsergebnisse	Leistungsbaseline + Optimierungsergebnisse
debug	Fehlerhaftes Verhalten beheben	Problem tritt nicht mehr auf + Regressionstests decken die Ursache ab	Soil = Ist (Behebung ist das Ziel)	Phänomen + Ursache + Reparaturstrategie + Präventionsmaßnahmen
refactor	Interne Struktur ändern, Verhalten unverändert	Alle vorhandenen Verhaltensweisen bleiben erhalten, alle Regressionstests grün	Soil = Ist ist zwingend erforderlich	Architekturdesign + Beschreibung der Strukturänderung

Stage-Lebenszyklus

Nach /plan-Ausgabe   Während der Umsetzung           Nach vollständiger Umsetzung     Bei Ausführung von /ship
     │                          │                            │                      │
     ▼                          ▼                            ▼                      ▼
   Gerüst erstellen            Dokumente und              Stage abschließen        Prüfen, ob Stage existiert
  (MISSION +                   Contract-Index             (Endzustands-Sperre,      (pre-launch
   Soil-Dokument-Pfade,        pflegen                    Ist-Dokumente,            checklist
   Umsetzungsplan-Links)       (Status, Abweichungen,     ADR,                      Sperrkriterium)
                                Nachweiszusammenfassung)   Abweichungsanalyse,
                                                            Validierungsergebnisse,
                                                            Lernzusammenfassung)

Erstellung (Gerüstphase)

Nachdem /plan die Dateien tasks/plan.md und tasks/todo.md ausgegeben hat, fragt der Agent den Benutzer, ob ein Stage-Dokument erforderlich ist. Nach Bestätigung durch den Benutzer:

Verzeichnis stages/<stage-id>/ erstellen (stage-id ist ein kurzer Titel in kebab-case)
STAGE.md-Gerüst erstellen, vorausgefüllt mit:
- Typ (feat | opt | debug | refactor)
- Status auf draft setzen
- Entscheider
- MISSION (aus der Spezifikation extrahiert)
- Pfade zu Soil-Dokumenten (mit TODO markiert)
- Links zum Umsetzungsplan (eintragen: tasks/plan.md und tasks/todo.md)
- Vorwärtsverweisungstabelle für Task-Contracts (anfangs leer)
- Ist-Dokumente (mit TODO markiert – nach Abschluss der Umsetzung ausfüllen)
- ADR (mit TODO markiert – mindestens ein Eintrag pro Stage, nach Abschluss der Umsetzung ausfüllen)
- Validierungsergebnisse (mit TODO markiert)
Eine Zeile in stages/INDEX.md anhängen

Befüllung (Aufbauphase)

Während der Umsetzung:

Bei Abschluss normaler Aufgaben muss STAGE.md nicht geändert werden; aber bei erstmaligem Ablegen eines Contracts, Statusänderung oder Rückmeldung von Abweichungen/Nachweisen muss es synchronisiert werden
Wenn Soil-Dokumente (spez, api-contract) erstellt werden, die entsprechenden Links aktualisieren und TODO-Markierungen entfernen
Contracts werden nur von STAGE.md vorwärtsverwiesen; keine Stage-Felder oder Rückverweise in Contracts hinzufügen
Nicht-none-Abweichungen von Contracts werden in die Tabelle „Soil vs. Ist-Differenzen“ übernommen, nicht erst beim Abschluss aus dem Gedächtnis nachgetragen

Abschluss (nach Fertigstellung)

Nachdem alle Aufgaben abgeschlossen und validiert sind, erinnert der Agent den Benutzer an den Abschluss. Nach Bestätigung durch den Benutzer:

task-contract/ mit der Indextabelle abgleichen: keine Auslassungen, toten Links oder Statusabweichungen
Sicherstellen, dass alle Contract-Status COMPLETED oder CANCELLED sind; ein DRAFT, READY oder BLOCKED_BY_ARCHITECTURE verhindert den Abschluss
Ist-Dokument-Links ausfüllen (api-doc, ADR)
Tabelle Soil vs. Ist-Differenzen ausfüllen (mit Spalte „Soil-Dokument rückwirkend aktualisiert?“), einschließlich sinnvoller Abweichungen aus Contract-Berichten
Validierungsergebnisse ausfüllen und erforderliche Nachweise aus Contracts verlinken
Lernzusammenfassung ableiten („Nächstes Mal so machen“ und „Nächstes Mal nicht so machen“)
Status auf done ändern
Entsprechende Zeile in stages/INDEX.md aktualisieren

Prüfung (vor Veröffentlichung)

Die Pre-Launch-Checkliste von /ship enthält:

„□ Gibt es für wesentliche Änderungen ein entsprechendes Stage-Dokument?“ – wenn für diese Runde ein Stage erstellt wurde, ist dies ein Sperrkriterium

Stage-Vorlage

Nachfolgend die standardisierte Vorlage für stages/<stage-id>/STAGE.md:

# Stage: [Kurzer Titel]

**Typ**: feat | opt | debug | refactor
**Datum**: YYYY-MM-DD — YYYY-MM-DD
**Status**: draft | in-progress | done | abandoned | superseded | split
**Entscheider**: @username

---

## MISSION (Ziel dieser Runde)

<!-- feat / opt / refactor verwenden das Standard-MISSION-Format -->

- **Ziel**: [Ein Satz, der beschreibt, was diese Runde erreichen soll]
- **Benutzer**: [Wer profitiert davon]
- **Erfolgskriterium**: [Woran erkennt man die Fertigstellung – konkret, überprüfbar]
- **Einschränkungen**: [Bindende Grenzen – technisch, ressourcenbezogen, zeitlich]
- **Nicht im Umfang**: [Explizit ausgeschlossene Inhalte und Gründe]

<!-- debug-Typ ersetzt durch folgende Struktur: -->
<!--
- **Phänomen**: [Was der Benutzer getan hat, was er gesehen hat, was er hätte sehen sollen]
- **Auswirkung**: [Betroffener Bereich, Dauer, Risiko für Datenintegrität]
- **Ursachenhypothese**: [Erste Einschätzung – nach Abschluss der Umsetzung auf bestätigte Ursache aktualisieren]
- **Reparaturstrategie**: [Notfallmaßnahme + Ursachenbehebung + Präventionsmaßnahmen]
- **Erfolgskriterium**: [Problem tritt nicht mehr auf, Regressionstests decken Ursache ab, ähnliche Probleme durch statische Prüfung abgedeckt]
-->

→ Siehe [MISSION.md](./MISSION.md)

---

## Soil-Dokumente (Wie wir es geplant haben)

| Dokument | Quell-Skill | Beschreibung |
|------|---------|------|
| [spez/xxx.md](./spez/xxx.md) | spec-driven-dev | Funktionsspezifikation |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | API-Vertrag |
| [design/xxx.md](./design/xxx.md) | — | [Ergänzende Beschreibung] |

> Vor Beginn der Umsetzung ausfüllen. Wenn eine Dokumentenart in dieser Runde nicht relevant ist, die entsprechende Zeile löschen.

---

## Umsetzungsplan

| Dokument | Quell-Skill | Beschreibung |
|------|---------|------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | Technisches Konzept |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | Liste atomarer Aufgaben |

---

## Task-Contracts (Delegations- und Ausführungsgrenzen)

> Nur schreibbare Delegationen, die die `delegated-task-contract`-Sperre benötigen, werden indiziert. Contract-Inhalt, Status und erforderliche Nachweise basieren auf der entsprechenden Datei; diese Tabelle speichert nur Vorwärtsverweise und Zusammenfassungen, ohne Rückverweise auf das Stage in den Contract zu schreiben.

| Task | Contract | Status | Abweichung / Nachweis |
|------|----------|------|----------------------|
| [Task-ID] | [Task-ID](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [Blockierung, Abweichung, Nachweis oder Abbruchgrund; wenn keine, `—` schreiben] |

> Wenn noch kein Contract vorhanden ist, die Tabellenüberschrift beibehalten und die Beispielzeile löschen. Tabelle nach erstmaligem Ablegen eines Contracts sowie bei jeder Status-, Abweichungs- oder Nachweisänderung synchronisieren.

---

## Ist-Dokumente (Wie es tatsächlich geworden ist)

> Nach Abschluss der Umsetzung diesen Abschnitt ausfüllen.

| Dokument | Quell-Skill | Beschreibung |
|------|---------|------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | Tatsächliche API-Dokumentation |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | Architekturentscheidungsaufzeichnung (Pflicht, mindestens ein Eintrag pro Stage) |

### ADR (Pflicht)

Jedes Stage **muss** mindestens einen ADR hervorbringen. ADRs dokumentieren wichtige Architekturentscheidungen und ihren Kontext.

| ADR | Entscheidungsinhalt | Alternativen |
|-----|---------|---------|
| [ADR-XXX](./docs/adr/XXX.md) | [Ein Satz, der die Entscheidung beschreibt] | [Abgelehnte Optionen und Gründe] |

**ADR-Inhaltsanforderungen:**
- Festhalten, „warum A statt B gewählt wurde“
- Aufzählen der in Betracht gezogenen und abgelehnten Alternativen mit Gründen
- Beschreibung der Einschränkungen und Konsequenzen der Entscheidung
- Wenn die Entscheidung mit einem bestehenden ADR zusammenhängt, explizit darauf verweisen

**ADR-Schwerpunkt nach Stage-Typ:**

| Stage-Typ | Typischer ADR-Inhalt |
|-----------|-------------|
| **feat** | Warum diese Architektur/dieses Framework/dieses Protokoll gewählt wurde; Design-Kompromisse des Datenmodells |
| **opt** | Warum diese Optimierungsstrategie gewählt wurde; warum andere Optionen (z.B. Cache vs. Indexoptimierung) nicht gewählt wurden |
| **debug** | Warum die Ursache entstanden ist; warum dieser Reparaturansatz gewählt wurde; Design der Präventionsmaßnahmen |
| **refactor** | Warum diese neue Struktur gewählt wurde; warum bestimmte Randfälle nicht vereinheitlicht wurden; Vergleich alter vs. neuer Struktur |

---

## Soil vs. Ist-Differenzen

> Nach Abschluss der Umsetzung ausfüllen. Jede sinnvolle Abweichung zwischen Plan und tatsächlicher Umsetzung festhalten.

Wenn der Bericht über die erforderlichen Nachweise eines Contracts eine nicht-`none`-Abweichung meldet, wird die Abweichung bei der Abnahme des Contracts gleichzeitig in diese Tabelle übernommen; nicht nur im Contract vermerken.

| Differenz | Soil (Plan) | Ist (Ergebnis) | Grund | Soil-Dokument rückwirkend aktualisiert? |
|------|------------|------------|------|-------------------|
| [Kurzbeschreibung] | [Wie war es geplant] | [Wie ist es tatsächlich] | [Warum die Abweichung] | Ja / Nein |

**Erläuterung der Spalte „Soil-Dokument rückwirkend aktualisiert?“:**
- **Ja**: Die Abweichung wird als korrekte Designrichtung anerkannt; die Spezifikation oder der API-Vertrag wurde nachträglich an die Ist-Situation angepasst
- **Nein**: Die Abweichung stellt einen temporären Kompromiss oder eine Notlösung dar; das Soil-Dokument bleibt unverändert, damit nachfolgende Stages darauf Bezug nehmen können
- Alle mit „Nein“ markierten Differenzzeilen sind Kandidaten für das nächste Backlog

---

## Validierungsergebnisse

| Prüfpunkt | Status | Nachweis |
|--------|------|------|
| [Abnahmekriterium 1] | ✅ / ❌ | [Testbericht, Leistungsdaten, Screenshot usw.] |
| [Abnahmekriterium 2] | ✅ / ❌ | [Nachweis] |
| Keine Regression | ✅ / ❌ | CI-Ausführungslink |

→ Siehe [VERIFY.md](./VERIFY.md)

---

## Lernzusammenfassung

> Beim Abschluss ausfüllen. Nicht mehr als zwei Sätze.

- **Nächstes Mal so machen**: [Was wurde in dieser Runde richtig gemacht – nachahmenswert in anderen Stages]
- **Nächstes Mal nicht so machen**: [Was wurde in dieser Runde falsch gemacht – sollte vermieden, beachtet oder verbessert werden]

---

## Verknüpfungen

- **Vorherige Stage**: [STAGE-XXX](../stage-XXX/STAGE.md) (oder „keine“)
- **Nächste Runde geplant**: [Kurzbeschreibung, oder „keine“]

Ergänzung (nach Abschluss anhängen)

Wenn nach dem Abschluss eines Stages (Status done) kleine Probleme behoben werden müssen, die jedoch kein neues Stage rechtfertigen, kann am Ende der STAGE.md ein ergänzender Abschnitt angehängt werden:

---

## Ergänzung 1 (2026-07-28)

- **Änderung**: [Kurzbeschreibung, was repariert wurde]
- **Grund**: [Warum diese Reparatur nach dem Abschluss noch erforderlich war]
- **Auswirkungsbereich**: [Welche Dateien/Module betroffen sind]

Beim Anhängen von Ergänzungen:

Der Stage-Status bleibt done, wird nicht auf in-progress zurückgesetzt
Ergänzungen werden chronologisch angehängt
Wenn die Reparatur eine neue ADR-Entscheidung erfordert, wird diese in die ADR-Tabelle der Ist-Dokumente aufgenommen und mit [Ergänzung 1] gekennzeichnet
Bei mehr als 3 kumulierten Ergänzungen sollte geprüft werden, ob ein neues Stage erstellt werden sollte, anstatt weiterhin Ergänzungen anzuhängen

INDEX.md

stages/INDEX.md ist der Navigations-Einstieg für alle Stages. Es wird bei der Erstellung und beim Abschluss eines jeden Stages gepflegt.

# Stage-Index

| ID | Titel | Typ | Status | Betroffene Module | Datum |
|----|------|------|------|---------|------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

Wartungsregeln:

Bei Erstellung eines Stages eine Zeile anhängen, Status draft
Beim Abschluss eines Stages Status auf done aktualisieren
Wenn ein Stage auf abandoned, superseded oder split wechselt, entsprechend aktualisieren
Betroffene Module listet die betroffenen Top-Level-Module/Verzeichnisse auf, um die Suche nach Modulen zu erleichtern

Statusmodell

Status	Bedeutung	Wann verwenden
`draft`	Gerüst erstellt, Umsetzung noch nicht begonnen	Nach Erstellung des Stages
`in-progress`	Wird gerade umgesetzt	Während der Umsetzung (optional)
`done`	Planmäßig abgeschlossen, Stage versiegelt	Alle Aufgaben erledigt, Validierung bestanden, Lernzusammenfassung geschrieben
`abandoned`	Vorzeitig aufgegeben	Falsche Richtung, Anforderung gestrichen, durch höhere Priorität unterbrochen
`superseded`	Von einem anderen Stage überdeckt	Stage-B hat den Umfang von Stage-A übernommen
`split`	In mehrere kleinere Stages aufgeteilt	Stage zu groß, in unabhängige Sub-Stages aufgeteilt

Behandlung von abandoned:

MISSION-Abschnitt aktualisieren, einen Absatz „Abbruchgrund“ anhängen
In der ADR-Tabelle mindestens einen Eintrag belassen, der dokumentiert, „warum nicht weitergemacht wurde“
Lernzusammenfassung wie gewohnt ausfüllen – die Lehren aus einem Abbruch sind oft wertvoller als die aus einem Erfolg
Ob Code/Dokumente des aufgegebenen Stages, die bereits abgeschlossen waren, zurückgerollt werden müssen, entscheidet der Entscheider und hält dies im ADR fest
Im Abschnitt „Verknüpfungen“ wird „Nächste Runde geplant“ durch „Keine (aufgegeben)“ ersetzt

Behandlung von superseded:

MISSION-Abschnitt aktualisieren, einen Absatz hinzufügen: „Durch welches Stage ersetzt und warum“
Im Abschnitt „Verknüpfungen“ hinzufügen: „Ersetzt durch: STAGE-XXX“
Status auf superseded ändern
Auf dem ersetzten Stage keine Ergänzungen mehr vornehmen – alle weiteren Arbeiten gehen auf das ersetzende Stage über

Behandlung von split:

MISSION-Abschnitt aktualisieren, einen Absatz hinzufügen: „Aufgeteilt in welche Sub-Stages und warum“
Im Abschnitt „Verknüpfungen“ hinzufügen: „Aufgeteilt in: STAGE-XXX, STAGE-YYY“
Status auf split ändern
Auf dem ursprünglichen Stage keine Ergänzungen mehr vornehmen – alle Arbeiten gehen auf die Sub-Stages über

Verzeichnisstruktur

stages/
  INDEX.md                      ← Index, eine Zeile pro Stage
  001-raft-election-optimization/
    STAGE.md                    ← Stage-Verbindungsdokument
    MISSION.md                  ← Detaillierte Zielbeschreibung (optional, für komplexe Projekte empfohlen)
    spez/                       ← Soil: Funktionsspezifikation
    design/                     ← Soil: Protokollverträge, Datenlayout
    tasks/
      plan.md                   ← Umsetzungsplan
      todo.md                   ← Aufgabenliste
    task-contract/              ← Delegations- und Ausführungsgrenzen, auf gleicher Ebene wie tasks/spez
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← Ist: Protokolldokumentation, RPC-Schnittstellen
      adr/                      ← Ist: Architekturentscheidungsaufzeichnung (Pflicht)
    verify/                     ← Validierungsnachweise
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Abgesehen vom Zuordnungspfad der Task-Contracts ist die Verzeichnisstruktur eine empfohlene Konvention. Die Kernanforderungen sind: STAGE.md muss vorhanden sein, jedes Stage enthält mindestens einen ADR; wenn Task-Contracts vorhanden sind, müssen sie im task-contract/-Verzeichnis des Stages liegen und von STAGE.md vorwärtsverwiesen werden.

Interaktion mit anderen Skills

Skill	Interaktionsweise
spec-driven-development	Die MISSION des Stages wird aus dem Objective der Spezifikation extrahiert
planning-and-task-breakdown	Nach `/plan`-Ausgabe fragt der Agent, ob ein Stage-Gerüst erstellt werden soll
delegated-task-contract	Contract wird im `task-contract/` des aktuellen Stages gespeichert; `STAGE.md` indiziert einseitig seinen Status, Abweichungen und Nachweise, der Contract verweist nicht zurück auf das Stage
api-and-interface-design	Sowohl Protokollverträge (gRPC/protobuf) in den Soil-Dokumenten als auch Schnittstellendokumentation in den Ist-Dokumenten werden mit dem Stage verlinkt
failure-injection-testing	Bei Fehlertoleranz und Wiederherstellung werden Fehlerinjektionspläne und Chaos-Experimentberichte mit den Ist-Dokumenten des Stages verlinkt
consistency-and-durability-verification	Bei Speicher- oder Zustandsreplikation werden Konsistenz-/Dauerhaftigkeitsprüfberichte mit den Validierungsergebnissen des Stages verlinkt
Intelligenter Agent nativer Implementierungsprozess	Nach Abschluss und Validierung aller Aufgaben erinnert der Agent an den Abschluss des Stages
documentation-and-adrs	ADR ist eine Pflichtausgabe des Stages; jedes Stage hat mindestens einen ADR
shipping-and-launch	`/ship` prüft, ob ein Stage existiert (Sperrkriterium, wenn eines für diese Runde erstellt wurde)

Häufige Rechtfertigungsausreden

Rechtfertigungsausrede	Realität
„Diese Änderung ist zu klein, sie braucht kein Stage.“	Wenn die Änderung zu klein für ein Stage ist, braucht sie wahrscheinlich auch keinen ADR. Aber der Benutzer hat bereits entschieden, ein Stage zu erstellen – vertrauen Sie dem Urteil des Benutzers.
„Die Anforderung ist zu einfach, Soil und Ist werden sich kaum unterscheiden.“	Abweichungen gibt es überall – selbst bei der einfachsten Änderung kann es während der Umsetzung zu Abweichungen vom Plan kommen. Der Kernwert des Stages liegt genau darin, diese Abweichungen festzuhalten.
„Schreiben wir erst den Code, das Stage kommt später.“	Ein Stage vor dem Abschluss ist ein lebendiges Verzeichnis, das nicht auf einmal fertiggeschrieben werden muss. Aber das nachträgliche Schreiben bedeutet, dass die Abweichungsanalyse auf dem Gedächtnis basiert – und das Gedächtnis ist unzuverlässig.
„Das braucht keinen ADR.“	Jedes Stage hat mindestens eine Entscheidung, die es wert ist, festgehalten zu werden – selbst wenn es nur ist: „Wir haben den einfachsten Ansatz gewählt, weil die aktuellen Einschränkungen keinen komplexeren zulassen.“
„Es wurde bereits `abandoned`, eine Lernzusammenfassung ist sinnlos.“	Die Lehren aus einem Abbruch sind oft wertvoller als die aus einem Erfolg. Das Festhalten des Grundes für den Abbruch ist mindestens genauso wichtig wie das Festhalten des Grundes für den Erfolg.
„In der Differenztabelle reicht ein 'Nein', eine Erklärung ist nicht nötig.“	Jede Zeile der Differenztabelle ist eine Eingabe für zukünftige Entscheidungen. Eine mit 'Nein' markierte Zeile sagt dem nächsten Bearbeiter: „Hier gibt es technische Schulden, und sie wurden bewusst hinterlassen.“
„INDEX.md kann später nachgetragen werden.“	Der Wert von INDEX.md wächst mit der Anzahl der Stages – beim ersten Stage fällt es nicht auf, beim zehnten ist es eine Notwendigkeit. Pflegen Sie es von Anfang an.

Rote-Flaggen-Warnungen

STAGE.md wurde erstellt, aber MISSION ist leer – der Wert des Gerüsts liegt in der MISSION; ein Stage ohne Ziel ist nur ein Platzhalter
In den Ist-Dokumenten gibt es eine API-Dokumentation, aber keinen entsprechenden ADR – Verstoß gegen die Regel „jedes Stage mindestens einen ADR“
Die Differenztabelle ist leer, aber der Benutzer hat während der Umsetzung Abweichungen erwähnt – Abweichungen wurden nicht erfasst
Die Lernzusammenfassung enthält „Keine“ oder „Alles lief reibungslos“ – jedes Stage hat Lehren; wenn keine gefunden werden, wurde nicht tief genug reflektiert
Ein abandoned-Stage hat keinen „Abbruchgrund“ – wertvollste Information geht verloren
Eine Zeile in INDEX.md befindet sich über einen längeren Zeitraum im Status draft – entweder die Umsetzung vorantreiben oder als abandoned markieren; das Gerüst nicht verrotten lassen
Es gibt 3+ Ergänzungsabschnitte, aber die Aufteilung in ein neues Stage wurde nicht in Betracht gezogen – die Umfangseinschätzung dieser Runde war falsch; reflektieren statt weiter anhängen
Das Feld „Entscheider“ ist leer – bei Teamarbeit führt dies zu einem Bruch der Entscheidungsnachvollziehbarkeit
In task-contract/ gibt es Dateien, die nicht von STAGE.md indiziert werden, oder Indexlinks verweisen auf nicht vorhandene Contracts
Contract-Status, Abweichungen oder Nachweise haben sich geändert, aber die Stage-Tabelle enthält noch die alte Zusammenfassung
Ein Contract verweist zurück auf STAGE.md, sodass die Zugehörigkeit beidseitig gewahrt wird
Es gibt noch DRAFT-, READY- oder BLOCKED_BY_ARCHITECTURE-Contracts, aber das Stage wird als done markiert

Validierung

Nach Erstellung des Stage-Gerüsts:

stages/<stage-id>/STAGE.md ist vorhanden
Stage-Typ (feat | opt | debug | refactor) ist ausgefüllt
Status ist draft
Entscheider ist ausgefüllt
MISSION ist ausgefüllt (Standardformat oder debug-Format, je nach Typ)
Umsetzungsplan-Links verweisen auf tasks/plan.md und tasks/todo.md
Abschnitt „Task-Contracts (Delegations- und Ausführungsgrenzen)“ und leere Vorwärtsverweisungstabelle wurden erstellt
[ stages/INDEX.md wurde um die entsprechende Zeile ergänzt

Nach Abschluss des Stages:

13eholder/zflow

Was ist zflow?

In Ihrer bevorzugten KI fragen

Dokumentation