# Doku-Aufräumung — Design **Datum:** 2026-04-25 **Status:** Entwurf **Scope:** Strukturelle Bereinigung der Repo-Doku nach erreichten Kernzielen (SPA + Pipeline + Multilingual live). Keine Code-Änderungen. Ziel ist ein ehrlicher Doku-Stand mit klarer Rollenverteilung der Top-Level-Dokumente, korrekten Status-Feldern in den Specs und einer sichtbaren Trennung zwischen "lebender Doku" und "Geschichte". ## Auslöser Die Inventur am 2026-04-25 hat drei strukturelle Probleme aufgedeckt: 1. **Specs lügen über ihren Status.** Die zwei ältesten Specs sagen "Entwurf, ausstehende User-Freigabe", obwohl beide seit dem 18. April live sind. Eine Spec hat ein abweichendes Header-Format (`**Stand:**` statt `**Status:**`). 2. **Pläne sind Geschichte, stehen aber im aktiven Blickfeld.** Alle sechs Pläne haben 0 abgehakte Checkboxen, obwohl die zugehörigen Features nachweislich live sind. STATUS.md sagt "alle Pläne erledigt" — das stimmt für die fünf Multilingual-/SPA-/Pipeline-Pläne, kollidiert aber mit `2026-04-21-prerender-snapshot.md`, der nicht umgesetzt ist. 3. **Vier Top-Level-Dokumente überlappen.** README, STATUS.md, HANDOFF.md und CLAUDE.md verlinken jeweils unterschiedliche Teilmengen der Specs; keine klare Single-Source-of-Truth für Konventionen vs. Logbuch vs. Außensicht vs. Session-Einstieg. ## Ziele - Specs spiegeln den realen Implementierungsstand wider. - Pläne sind als Historie sichtbar archiviert; was noch nicht umgesetzt ist, ist als solches gekennzeichnet. - Jedes Top-Level-Dokument hat genau eine Rolle, und die ist im Doc selbst benannt. - Wiki-Entwürfe haben einen expliziten Status: lebend, eingefroren oder publiziert. Ausdrücklich **nicht** Ziel: - Inhaltliche Überarbeitung der Specs (keine Detail-Korrekturen am Designgehalt, nur Status und Querverweise). - Konsolidierung von STATUS.md + HANDOFF.md zu einem Dokument — die beiden Rollen sollen erhalten bleiben, nur klarer abgegrenzt. ## Maßnahmen ### M1 — Specs: Status-Header vereinheitlichen und nachziehen **Konvention** (gilt fortan für alle Specs): ```markdown # **Datum:** YYYY-MM-DD **Status:** **Scope:** ``` Die einheitliche Status-Stufenfolge: `Entwurf` → `In Umsetzung` → `Umgesetzt (live seit …)`. Alternative Endstände: `Eingefroren` (Idee gut, aber nicht aktiv verfolgt) oder `Verworfen` (mit kurzem Grund). Bei Status-Änderungen das Datum als Suffix in Klammern führen. **Pro Spec konkret:** - `2026-04-15-nostr-page-design.md` → `Status: Umgesetzt (live seit 2026-04-18)`. - `2026-04-15-publish-pipeline-design.md` → `Status: Umgesetzt (live seit 2026-04-18)`. Die Inline-Notiz "Designentscheidung 2026-04-16: Blossom für alle Bilder" bleibt im Body, der Header wird klar. - `2026-04-16-image-metadata-convention.md` → `Status: Umgesetzt — Phase 1 (live seit 2026-04-18)`. Body bleibt unverändert; die im Body bereits markierten Phase-2-Punkte (Caption-Rendering, Reverse-Routine, License-Katalog, strikte Validierung) bleiben offen. - `2026-04-21-multilingual-posts-design.md` → bereits korrekt, Format ggf. minimal nachziehen (`Umgesetzt (live seit 2026-04-21)`). - `2026-04-21-prerender-snapshot-design.md` → `**Stand:**` durch `**Status:** Entwurf` ersetzen, Datum-Zeile ergänzen. Hinweis im Body: "Plan-Pendant unter `plans/archive/2026-04-21-prerender-snapshot.md` liegt noch unbearbeitet vor." ### M2 — Pläne ins Archiv **Aktion:** ```sh mkdir -p docs/superpowers/plans/archive git mv docs/superpowers/plans/2026-04-15-spa-sveltekit.md \ docs/superpowers/plans/2026-04-16-publish-pipeline.md \ docs/superpowers/plans/2026-04-21-multilingual-posts-pipeline.md \ docs/superpowers/plans/2026-04-21-multilingual-posts-spa.md \ docs/superpowers/plans/2026-04-21-multilingual-posts-i18n.md \ docs/superpowers/plans/2026-04-21-prerender-snapshot.md \ docs/superpowers/plans/archive/ ``` **Begründung:** Alle sechs Pläne sind entweder umgesetzt (5) oder eingefroren (1, prerender-snapshot). Keiner ist aktuell aktiv. Die Trennung "Plans-Verzeichnis = aktive Pläne" / "Archive = Geschichte" hält das aktive Blickfeld leer und ehrlich. **Checkboxen werden NICHT retrospektiv nachgepflegt.** Die archivierten Pläne bleiben so wie sie sind. Wer den Soll-Stand wissen will, liest STATUS.md und die zugehörige Spec. **`plans/archive/README.md` neu anlegen**, ein paar Zeilen, ungefähr: ```markdown # Plan-Archiv Diese Pläne sind abgearbeitet (5) oder zu Eis gelegt (1). Checkboxen spiegeln nicht den realen Umsetzungsstand wider — sie wurden während der Umsetzung nicht nachgepflegt. Verbindlicher Stand ist STATUS.md und die jeweilige Spec. | Plan | Spec | Stand | |---|---|---| | 2026-04-15-spa-sveltekit | nostr-page-design | umgesetzt 2026-04-18 | | 2026-04-16-publish-pipeline | publish-pipeline-design | umgesetzt 2026-04-18 | | 2026-04-21-multilingual-posts-pipeline | multilingual-posts-design | umgesetzt 2026-04-21 | | 2026-04-21-multilingual-posts-spa | multilingual-posts-design | umgesetzt 2026-04-21 | | 2026-04-21-multilingual-posts-i18n | multilingual-posts-design | umgesetzt 2026-04-21 | | 2026-04-21-prerender-snapshot | prerender-snapshot-design | eingefroren | ``` `docs/superpowers/plans/` bleibt als Verzeichnis erhalten (mit `.gitkeep`), damit die Konvention "hier liegen aktive Pläne" sofort wieder genutzt werden kann, wenn ein neuer Plan entsteht. ### M3 — Top-Level-Dokumente: Rollen festlegen Pro Dokument ein **Rollensatz** ganz oben (unter dem Titel), so dass beim Reinklicken sofort klar ist, wofür es da ist. | Datei | Rolle | Zielgruppe | |---|---|---| | `README.md` | Außensicht: was ist das Repo, wie funktioniert es grob, wo geht's weiter | Besucher:innen, GitHub-Crawler | | `docs/STATUS.md` | Logbuch: aktueller Stand + Erledigt-Chronologie | Jörg + Claude beim Wiedereinstieg | | `docs/HANDOFF.md` | Konventions-Handbuch: wie man hier arbeitet (Posts, Übersetzungen, Deploys, Stolperfallen) | Jörg + Claude im Alltag | | `CLAUDE.md` | Session-Einstieg: Lese-Reihenfolge, Tonfall, kritische Fallstricke | Claude beim Session-Start | **Konkrete Edits:** - **README.md** — Lange Spec-/Plan-Linkliste auf 3 Specs eindampfen: SPA, Publish-Pipeline, Multilingual (das sind die drei, die das Außenbild der Seite erklären). Bild-Metadaten-Konvention und prerender-Spec sind interne Detail-Themen und gehören nicht in die README. Plan-Verlinkungen ganz raus, stattdessen ein Hinweis auf `docs/superpowers/plans/archive/`. Erste Zeile nach dem Titel: kurzer Rollensatz. - **STATUS.md** — Erste Zeile: Rollensatz. "Erledigt"-Chronologie bleibt, ist Logbuch. Widerspruch "alle Pläne erledigt" auflösen: Satz so umformulieren, dass prerender-snapshot als eingefrorenes Vorhaben separat aufgeführt ist. - **HANDOFF.md** — Rollensatz oben. Workflow-Inhalte und Stolperfallen bleiben. - **CLAUDE.md** — Rollensatz oben. Quick-Links auf den finalen Spec-Stand bringen (5 Specs inkl. prerender). "Kritische Fallstricke" bleibt unverändert (alle 5 Punkte sind aktuell relevant). **Single-Source-of-Truth-Regeln** (in HANDOFF.md kurz festhalten, damit zukünftiges Edit-Verhalten klar ist): - *Live-URLs / Setup-Stand* steht in **STATUS.md**. HANDOFF/README/CLAUDE zitieren oder verlinken, duplizieren nicht. - *Frontmatter-Konventionen, Workflows, Stolperfallen* stehen in **HANDOFF.md**. - *Spec-Liste* ist die Realität in `docs/superpowers/specs/` — README/CLAUDE.md verlinken nur die für ihre Zielgruppe relevanten. ### M4 — Wiki-Entwürfe: Status klären Drei Dateien, drei Entscheidungen: - `docs/redaktion-bild-metadaten.md` — Frontmatter-Block oben ergänzen: ```markdown **Status:** Schnappschuss vom 2026-04-18 — als Hilfsmittel für die Migrations-Sitzung erstellt, kein laufender Workflow. Bleibt als Referenz erhalten. ``` - `docs/wiki-entwurf-nostr-bild-metadaten.md` (DE) und `docs/wiki-draft-nostr-image-metadata.md` (EN) — beide bekommen oben: ```markdown **Status:** Eingefroren am 2026-04-25 — fertige Entwürfe für externe Veröffentlichung (NIP-Proposal / nostrbook.dev). Solange nicht publiziert, dient diese Repo-Kopie als Referenz und Geschichts-Dokument. ``` Bei späterer externer Veröffentlichung wird der Status auf `Publiziert (URL)` aktualisiert. ### M5 — `github-ci-setup.md` Ergänzung oben: ```markdown **Status:** Aktuell genutzt; mittelfristig zu ersetzen durch self-hosted CI (siehe HANDOFF.md → Option D). ``` Keine inhaltliche Änderung — die Setup-Schritte sind nach wie vor korrekt für die heute laufende Pipeline. ## Reihenfolge der Umsetzung 1. M1 — Spec-Header durchziehen (am wichtigsten, alles andere baut darauf auf). 2. M2 — Pläne archivieren + Archiv-README schreiben. 3. M3 — Top-Level-Dokumente (Rollensätze + Link-Bereinigung). 4. M4 + M5 — kleine Status-Stempel auf Wiki/CI-Doku. 5. Commit, ggf. in 2-3 logischen Schritten. ## Erfolgskriterien - `grep -r "ausstehende User-Freigabe" docs/superpowers/specs/` liefert nichts. - `ls docs/superpowers/plans/` zeigt nur `archive/` (+ ggf. `.gitkeep`). - Jede der vier Top-Level-Dateien beginnt mit einem Rollensatz. - README enthält keine Verweise auf einzelne Pläne mehr (nur auf das Archiv-Verzeichnis). - Specs haben einheitliches `**Status:**`-Format. ## Was bewusst nicht gemacht wird - **Keine inhaltliche Überarbeitung** der Specs. Falls beim Status-Update inhaltliche Lügen auffallen (z. B. Spec beschreibt Feature anders als es live ist), wird das in dieser Spec **nicht** mitgefixt — separat als eigenes Vorhaben aufnehmen. - **Keine Konsolidierung** von STATUS.md + HANDOFF.md. Beide bleiben bestehen, nur Rollen werden klarer benannt. - **Keine Frontmatter-Felder** (`status:`, `superseded-by:`) in den Specs. Text-Header reicht für die aktuelle Repo-Größe; YAML-Metadaten wären Overkill. - **Keine retrospektiven Checkbox-Updates** in den archivierten Plänen. ## Folgevorhaben (außerhalb dieser Spec) - **Paket B — SPA-Konsolidierung:** Tag-/Date-/Locale-Utilities extrahieren, Stores auf Runes migrieren, `PostView.svelte` entzerren. - **Paket C — Pipeline-Härtung:** `cli.ts` aufbrechen, Tests für `signer.ts` + `check.ts`, CWD-Sensitivität fixen. - Entscheidung über prerender-snapshot: weiterverfolgen oder verwerfen.