m1nga/iteration-close

iteration-close — destillieren, aussortieren, Übernahme beweisen, Bootstrap proben, Nächstes vorbereiten

Ein Produkt, das ewig iteriert, sammelt zwei stille Schulden an, und dieses Skill baut beide an jeder Iterationsgrenze ab – sicher (nichts geht verloren) aber gnadenlos (nichts Totes bleibt):

• Tote Dateien schlummern und verrotten zu Zweiwahrheiten – ein veralteter Zweig liegt wochenlang herum; ein Runbook behauptet noch, eine Komponente sei „nicht gebaut“, lange nachdem sie ausgeliefert wurde.
• Wissen, das nur in einem Chatfenster lebt, stirbt mit ihm – ganze funktionierende Pipelines sind in Scratchpads gestorben; hart erarbeitete Entscheidungen sterben mit der Sitzung. Behalte die Lektion, nicht das Artefakt.

Es ist generisch: es funktioniert in jedem Repo, indem es dessen eigene Konventionen liest, und wo eine Konvention fehlt, erstellt es das Minimum, anstatt Annahmen zu treffen oder einen Fehler zu werfen. „Ein neues Fenster oder eine neue Maschine kann weitermachen“ ist eine HOFFNUNG, bis sie GETESTET ist; aktuell sein (pull) ist immer sicher, aber veröffentlichen (push) ist eine bewusste Entscheidung. Antworte in der Sprache, in der der Benutzer arbeitet.

Zwei Ausführungsmodi

• Vollständiger Abschluss (Standard): alle fünf Phasen in Reihenfolge. Verwende dies, wenn eine Iteration/ein Abschnitt abgeschlossen ist und der Benutzer sie komplett abschließen möchte.
• Nur-Aussortieren (eigenständige Bereinigung): wenn der Benutzer nur darum bittet, alte/tote/überholte Dateien zu entfernen, führe Phase 2 allein aus – erzwinge NICHT den vollständigen Fünf-Akt-Abschluss. Vorbedingungen gelten weiterhin: Schritt 0 (Orientierung) ausführen, die Fail-Closed-Verweigerungsprüfungen, und eine Phase-1-Stichprobe, die auf das Löschinventar beschränkt ist – jedes Element, dessen Lektion oder Entscheidung nur im Chat lebt, wird zuerst in eine nachverfolgte Datei destilliert oder bleibt aus dem Inventar. Alle Phase-2-Regeln gelten unverändert, einschließlich der expliziten Ja-Bestätigung und der Quarantäneregel.

Schritt 0 – Orientiere dich in DIESEM Repo (entdecken, sonst Erstellung planen)

Lies das vorhandene Einstiegsdokument – CLAUDE.md / AGENTS.md / README / einen docs/-Index – und entdecke sechs Dinge. Verwende, was du findest; wo etwas fehlt, vermerke es als Lücke, die dieser Abschluss füllen wird (jede Phase unten sagt wie); erfinde niemals einen Pfad, der nicht existiert.

1. Lektionen-/Entscheidungsaufzeichnung – wo hinterlegt dieses Repo Entscheidungen? (CHANGELOG, docs/adr/, DECISIONS.md oder ein repo-spezifisches Register.) Wenn keins vorhanden, erstellt Phase 1 eine einzelne DECISIONS.md.
2. Bestätigter Upload-Befehl – ein bewusster Push-Schritt (bin/sync, make deploy, eine dokumentierte git push-Disziplin)? Wenn ja, DAS ist der Upload-Kanal; umgehe ihn niemals. Wenn keiner vorhanden, verwendet Phase 3a einen einfachen git push nach einem Diffstat + Bestätigung.
3. Bootstrap-Befehl – wie wird ein frischer Klon lebendig? (bin/bootstrap, bin/sync-setup, install.sh, make setup, eine Paketmanager-Installation.) Wenn keiner vorhanden, erstellt Phase 4 einen.
4. Testbefehl – aus der CI-Konfiguration, package.json-Skripten, einem Makefile oder der Sprachvorgabe (pytest / go test / cargo test / npm test). Wenn keiner auffindbar ist, hat das Repo noch keine ausführbare Testsammlung: Behandle dies als expliziten Zustand unten – interpretiere es nie als „grün“, lehne NIE ein Repo ab, das legitimerweise keines hat.
5. Grounding/Gate-Skill – ein Produkt-Grounding- oder Pre-Build-Gate-Skill? Wenn ja, ist dessen „After-Build“-Checkliste dein Pre-Close-Gate. (Produktspezifische Gates leben im Produkt-Repo; dieses Skill bleibt generisch und delegiert an sie.)
6. Deklarierte Daten-/Wiederherstellungs-/Quarantäneverzeichnisse – Verzeichnisse, die das Einstiegsdokument als echte Daten, Wiederherstellungsmaterial oder Quarantänedateien benennt. Diese sind von jeder „Archiv-förmige Verzeichnisse müssen nicht existieren“-Regel unten ausgenommen und dürfen niemals in einem Löschinventar erscheinen.

Ausführung verweigern (Fail-Closed)

Schließe nicht mitten in einer Iteration ab – du verlierst Haut UND Fleisch. VERWEIGERE (in beiden Ausführungsmodi), wenn: das Verzeichnis kein Git-Repository ist (stoppe und sage es – git init auszuführen ist die Entscheidung des Benutzers); die Testsammlung existiert und tatsächlich FEHLSCHLÄGT (eine fehlende Sammlung ist keine fehlschlagende – siehe Schritt 0.4); ein adversarielles Gate, falls das Repo eines hat, ausstehend ist oder CHANGES-REQUIRED lautet; oder ein anderer Agent/Lane unbestätigte Mid-Slice-Arbeit in Pfaden hat, die du berühren würdest. Sage, was blockiert, und stoppe.

Führe bei einem vollständigen Abschluss die Phasen IN REIHENFOLGE aus. Jede hat einen Ausstiegstest; fahre niemals nach einem fehlgeschlagenen Ausstieg fort.

Phase 1 – DESTILLIEREN (Rettungsgate: nichts stirbt, bevor seine Lektion gesichert ist)

1. Überführe die in Chats entstandenen Entscheidungen dieser Iteration in das Entscheidungsprotokoll des Repos (Schritt 0.1), jede mit ihrem Status und ihrer Quelle. Wenn das Repo Entscheidungen noch nirgends ablegt, ist die Erstellung des Protokolls Teil dieser Phase – eine einzelne DECISIONS.md im Repo-Root reicht aus. Eine Entscheidung, die nur in einem Chatfenster existiert, existiert nicht; hinterlasse keine destillierten Entscheidungen ohne verfolgte Heimat.
2. Neue Invarianten/Regeln, die in dieser Iteration entdeckt wurden → in die Contracts-Datei des Repos, oder falls nicht vorhanden, ins Entscheidungsprotokoll – idealerweise jeweils als Test. Wenn keines existiert, erstelle das Entscheidungsprotokoll und setze sie dort hinein. Lösche das Artefakt, behalte die Invariante.
3. Sitzungs-exklusive-Fähigkeitsprüfung: Hat diese Iteration auf etwas angewiesen, das NUR in einem Prompt, einem Scratchpad oder jemandes Gedächtnis lebt? Führe es ins Repo über (Code / Skill / Dokument) oder dokumentiere seinen bewussten Ausschluss. Benenne jedes explizit – hier sterben Pipelines.
4. Wenn sich die STRUKTUR geändert hat, aktualisiere – oder, wenn keine existiert und die Struktur jetzt nichttrivial ist, erstelle – eine kurze Architektur-/Systemnotiz, sodass sie noch die Realität beschreibt. Bringe ein Statusboard (z. B. ein Fortschrittsdokument) auf den aktuellen Stand, falls das Repo eines hat.

AUSSTIEGSTEST: Grep auf die wichtigsten Entscheidungen und Invarianten dieser Iteration innerhalb des Repos – jede in einer nachverfolgten Datei auffindbar. Alles nur im Chat Auffindbare = Phase 1 nicht abgeschlossen.

Phase 2 – AUSSORTIEREN (gnadenloses Löschen; Git-Historie ist das EINZIGE Archiv)

1. Erstelle ein Löschinventar mit Belegen, eine Zeile pro Element: Pfad | warum tot | was es ersetzt. Erfasse überholte Module/Spezifikationen, tote/leere Verzeichnisse, Entwicklungsrückstände (Scratch-Dateien, mktemp-ähnlichen Müll, Testdaten in echten Stores), abgeschlossene Plan-/TODO-Dokumente und VERALTETE DOKUMENTATION – führe einen Docs-vs-Code-Widerspruchsdurchlauf durch; ein Dokument, das etwas behauptet, was der Code widerspricht, ist schlimmer als keines. Markiere jede Zeile als TRACKED oder UNTRACKED (git ls-files --error-unmatch <Pfad>), da die beiden unterschiedliche Schicksale haben (Regeln 3 und 4).
2. Lege dem Benutzer das VOLLSTÄNDIGE Inventar vor und warte auf ein explizites Ja, bevor du etwas löschst. Teilweise Zustimmung ist in Ordnung – bearbeite nur die genehmigten Zeilen. Der Agent drückt niemals eigenständig irreversible Knöpfe; „der Benutzer hat um eine Bereinigung gebeten“ autorisiert die Erstellung der Liste, nicht deren Ausführung.
3. Nachverfolgte Dateien: nur git rm. KEINE _archive/-Verzeichnisse, KEIN .bak, KEINE alt-/legacy--Umbenennungen, KEINE auskommentierten Leichen. Wiederherstellung = Git-Historie, einen git revert entfernt – das ist das Archiv; ein Checkpoint-Commit vor dem Löschen macht es unverwundbar.
4. Nicht nachverfolgte oder git-ignorierte Dateien: NIEMALS direkt rm – die Git-Historie kann nicht wiederherstellen, was nie committed wurde. Dies ist die Datensicherheitslinie. Verschiebe sie stattdessen in das deklarierte Quarantäneverzeichnis des Repos (Schritt 0.6). Wenn keines deklariert ist, erstelle jetzt eines: .iteration-quarantine/ im Repo-Root, zu .gitignore hinzugefügt, im Einstiegsdokument mit einer Zeile deklariert („Quarantäne für nicht nachverfolgte Dateien, die auf Löschung warten – wird manuell vom Benutzer geleert“). Das Leeren der Quarantäne ist die Handlung des Benutzers – biete es bei einem zukünftigen Abschluss an, mit eigenem explizitem Ja; niemals stillschweigend.
5. Entsorge niemals die echten DATEN des Produkts, als wären sie Entwicklungsrückstände. Benutzer-/Kundenzustand, gespeicherte Sitzungen, echte Archive von Benutzerinhalten sehen wie Unordnung aus und sind die Seele des Produkts. Wenn ein Verzeichnis beides sein könnte, behandele es als Daten und behalte es; überprüfe vor jedem git rm.
6. Committe Löschungen in thematischen Gruppen; jede Nachricht sagt WARUM + was es ersetzt.
7. Nach dem Löschen: Alle zutreffenden Prüfungen müssen bestehen: Wenn das Repo eine Testsammlung hat, ist sie grün; Grep auf lose Verweise für jedes gelöschte Modul/Symbol ist leer (ein Import einer gelöschten Datei führt zu einem Startabsturz – eine echte Narbe); das Einstiegsdokument und Skill-Dokumente referenzieren keinen gelöschten Pfad.

AUSSTIEGSTEST: git status sauber, keine Archiv-förmigen Verzeichnisse vorhanden – außer Verzeichnisse, die das Einstiegsdokument als Daten, Wiederherstellung oder Quarantäne deklariert (Schritt 0.6) – loser Grep leer, und die Testsammlung grün, falls eine existiert.

Phase 3 – ZWEI BEREITSCHAFTSKANÄLE (unterschiedliche Anforderungen; getrennt prüfen)

Hochladen und Fortsetzbar-sein sind NICHT dasselbe Problem. Sie zu vermischen führt dazu, dass ein Repo „in die Cloud gepusht“ wird, während sein echter Zustand noch in einem Chat-Protokoll lebt. Prüfe jeden für sich.

3a. Bestätigter Cloud-Upload (das TRANSPORT-Problem)

1. Geheimer Scan nur auf TRACKED-Dateien (sk-ant / ghp_ / gho_ / github_pat / AKIA / xox[baprs] / consumer_secret / access_token / Bearer / BEGIN PRIVATE KEY / .env-Formen). Jeder Treffer → stoppe, säubere, scanne erneut.
2. Prüfe git remote. Wenn es KEINEN Remote gibt, braucht der Upload einen, den der BENUTZER bereitstellt – das Hinzufügen eines Remotes ist eine Konfigurationsänderung, also bestätige mit dem Benutzer oder vermerke „noch kein Remote – Veröffentlichung zurückgestellt“ und springe zu 3b, anstatt bei einem bloßen Git-Befehl einen Fehler zu werfen.
3. Mit einem Remote: zeige git log @{u}..HEAD --oneline + Diffstat (fallback auf „alle lokalen Commits“, wenn es noch keinen Upstream gibt) – genau das, was diese Maschine verlassen wird.
4. Upload über den bestätigten Upload-Befehl des Repos (Schritt 0.2) nach Bestätigung durch den Benutzer; wenn das Repo keinen hat, git push nach Diffstat und einem Ja. Niemals automatisch pushen.

3b. Null-Kontext-Übernahme (das WISSENSVOLLSTÄNDIGKEITS-Problem) – der Kaltstart-Test

1. Hole EINEN wirklich kontextfreien Leser ins Repo – in Claude Code: starte einen frischen Unteragenten (Task-Tool); in Codex: führe einen frischen codex exec oder eine neue Sitzung ohne vorherigen Kontext aus; auf jeder nackten Umgebung: öffne eine neue Sitzung und füge NUR den Repo-Pfad plus die Fragen ein, niemals dieses Gespräch. Gib ihm nur den Repo-Pfad und: „Lies dieses Repo kalt von seinem Einstiegsdokument. Beantworte dann: (1) Was ist dieses Produkt in einem Satz; (2) wo steht die Arbeit (erledigt / als nächstes); (3) was würdest du als nächstes tun und warum; (4) nenne drei Dinge, die du hier niemals tun darfst.“
2. Bewerte seine Antworten anhand der kanonischen Dokumente des Repos. Wenn das Repo überhaupt kein Einstiegs-/kanonisches Dokument hat, ist die Erstellung eines minimalen (das Produkt in einem Satz, aktueller Zustand erledigt/als nächstes, drei Never-Dos) Teil dieses Abschlusses – es ist das Artefakt, das der Test bewertet. Führe den Test nicht gegen das Nichts aus.
3. Jede falsche oder fehlende Antwort ist ein ÜBERNAHME-DOKUMENT-FEHLER, nicht die Schuld des Testers. Korrigiere (oder erstelle) das Dokument, führe mit einem NEUEN frischen Leser erneut aus. Wiederhole, bis ein kalter Leser 4/4 erreicht, begrenzt auf 3 Runden – wenn es nach 3 immer noch fehlschlägt, liste die verbleibenden Lücken auf und übergib die Entscheidung an den Benutzer.

AUSSTIEGSTEST: Test besteht 4/4. Erst dann ist „jedes neue Fenster / jede neue Maschine kann weitermachen“ eine getestete Tatsache.

Phase 4 – EIN-KOMMANDO-BOOTSTRAP (geprobt, nicht angenommen)

1. Stelle sicher, dass der Bootstrap des Repos (Schritt 0.3) existiert und aktuell ist – idempotent, sicher wiederholbar: überprüfe Toolchain-Versionen; verknüpfe Sync/Konfiguration; installiere Abhängigkeiten; führe die Testsammlung aus, falls eine existiert; gib den aktuellen Status + die NAMEN aller fehlenden lokalen Geheimnisse aus (niemals Werte, z. B. „config.local.json fehlt – nur für Live-Veröffentlichung benötigt“); beende mit einem Exit-Code ungleich null bei jedem Fehler mit einem einzeiligen Grund. Wenn noch kein Bootstrap existiert, ist dies die Iteration, um einen zu erstellen.
2. PROBE IHN: Klone das Repo in ein Scratch-Verzeichnis (von der Origin-URL oder vom lokalen Repo-Pfad, wenn noch kein Remote existiert) und führe den Bootstrap dort aus. Er muss grün enden mit NULL manuellen Schritten. Lösche den Proben-Klon danach.
3. Die Neuer-Maschine-Geschichte muss nach diesem Probelauf eine Zeile lang sein und STIMMEN: git clone <origin-url> <dir> && cd <dir> && <bootstrap-befehl>. Wenn noch kein Remote existiert, vermerke, dass diese Zeile noch nicht wahr ist, bis der Benutzer einen setzt – veröffentliche sie nicht, als ob sie funktioniert.

AUSSTIEGSTEST: Der Proben-Klon bootstrapt grün, unberührt von Menschenhand.

Phase 5 – ABSCHLUSS + STARTVORBEREITUNG (Kontinuität)

1. Tagge die Iteration: git tag iter-<N>-<slug> (annotiert, einzeilige Zusammenfassung). N = 1 + die Anzahl vorhandener iter-*-Tags (`git tag --list