From 21797a005aa24ba75167b00bb32335d24b896c65 Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Thu, 20 Aug 2026 12:00:00 +0000 Subject: [PATCH] FRAMEWORK-BEFUNDE.md: wo das Verfahren nicht getragen hat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Auf Wunsch von sorb: eine Eingangsliste fuer die Framework-Ernte, damit wiederkehrende Fehlerklassen in der naechsten neckbeard-Iteration nicht erneut passieren muessen. Je Befund kurze Beschreibung, Ursachen-Einschaetzung, Belege und ein Vorschlag. Name bewusst FRAMEWORK-BEFUNDE statt 'Framework Defects': 'Befund' ist im Projekt der feststehende Begriff (gruppenpruefung meldet Befunde, quittungen quittiert sie, AGENTS.md: 'Jeder Befund gehoert als Issue erfasst'). 'Defect' waere zudem zu eng - das Uebergehen der AAR-Pflicht ist kein Defekt DES Frameworks, sondern eine Abweichung, die eine Luecke darin sichtbar macht. Umbenennen ist ein git mv. Sieben Erstbefunde, alle aus dieser Sitzung belegt: FB-01 AAR-Pflicht setzt sich ohne Werkzeug nicht durch FB-02 'meldet Erfolg, ist aber blind' - sieben Vorkommen, fuenf Werkzeuge FB-03 Pruefungen erzeugen Befunde, die niemand beheben kann FB-04 Issues behaupten Zustaende, die laengst ueberholt sind FB-05 Dashboards und Pruefungen ohne Datenbeleg FB-06 Dokumente werden ergaenzt, aber nicht revidiert FB-07 Werkzeuge messen unbemerkt die falsche Instanz Verlinkt in README (Struktur) und roadmap (Kadenz, bei der Retro) - eine Datei, die niemand findet, waere selbst ein Befund der Klasse FB-06. ⚠️ validate.py prueft nur unterhalb von docs/. Diese Datei ist damit NICHT schema-geprueft - bei einer Liste ueber fehlende Durchsetzung ist das eine Ironie, die im Refinement einen Blick wert ist. --- FRAMEWORK-BEFUNDE.md | 177 +++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + roadmap.md | 3 + 3 files changed, 181 insertions(+) create mode 100644 FRAMEWORK-BEFUNDE.md diff --git a/FRAMEWORK-BEFUNDE.md b/FRAMEWORK-BEFUNDE.md new file mode 100644 index 0000000..b6cc440 --- /dev/null +++ b/FRAMEWORK-BEFUNDE.md @@ -0,0 +1,177 @@ +# Framework-Befunde + +> **Wofür diese Datei da ist:** Stellen, an denen das Verfahren nicht getragen hat — +> weil ihm etwas fehlt, weil niemand widersprochen hat, oder weil derselbe Fehler +> wiederkam. Sie ist die Eingangsliste für die **Framework-Ernte**: Was hier steht, +> soll in der nächsten neckbeard-Iteration nicht erneut passieren müssen. +> +> **Was hierher gehört:** wiederkehrende Fehlerklassen, Abweichungen vom Verfahren, +> Regeln, die sich ohne Werkzeug nicht durchsetzen, und Prüfungen, die etwas melden, +> das niemand beheben kann. +> +> **Was nicht:** normale Issues (die gehören nach `docs/issues/`) und einzelne +> Vorfälle (die gehören als AAR nach `docs/aar/`). Hier steht, was aus mehreren +> davon als **Muster** hervorgeht. +> +> **Pflege:** Ein Befund wird `geerntet`, wenn die nächste Iteration ihn abdeckt — +> nicht schon, wenn er einmal behoben wurde. Das Refinement geht die offenen durch. + +## Übersicht + +| # | Befund | Klasse | Stand | +|---|---|---|---| +| FB-01 | Die AAR-Pflicht setzt sich ohne Werkzeug nicht durch | Durchsetzung | offen | +| FB-02 | „Meldet Erfolg, ist aber blind" — sieben Vorkommen in fünf Werkzeugen | Fehlerklasse | offen | +| FB-03 | Prüfungen erzeugen Befunde, die niemand beheben kann | Verfahrenslücke | teilweise | +| FB-04 | Issues behaupten Zustände, die längst überholt sind | Verfahrenslücke | offen | +| FB-05 | Dashboards und Prüfungen ohne Datenbeleg | Fehlerklasse | offen | +| FB-06 | Dokumente werden ergänzt, aber nicht revidiert | Fehlerklasse | offen | +| FB-07 | Werkzeuge messen unbemerkt die falsche Instanz | Fehlerklasse | offen | + +--- + +## FB-01 — Die AAR-Pflicht setzt sich ohne Werkzeug nicht durch + +**Beschreibung.** `roadmap.md` verlangt einen AAR nach jedem Deploy mit Übergabe und nach +Incidents. Zwischen dem 17. und 20.08.2026 gab es **sechs** solche Ereignisse. Geschrieben +wurde zunächst **keiner**; alle sechs entstanden nachträglich auf Nachfrage von sorb. + +**Ursachen-Einschätzung.** Nicht Nachlässigkeit, sondern eine strukturelle Asymmetrie: +Im selben Zeitraum wurde **kein einziges Mal** vergessen, was ein Werkzeug prüft — +Frontmatter (`validate.py`), `STATUS.md` (`gen_status --check`), Spiegel +(`spiegel_issues.py`), Commit-Konvention (`gruppenpruefung.py`). Der Unterschied ist, **wer +widerspricht**. Der AAR-Pflicht widerspricht niemand. + +Verschärfend: Die Regel steht in `roadmap.md`, nicht in `AGENTS.md` — und auf `AGENTS.md` +verweist jedes `CLAUDE.md`. Wer nur der Zeigerkette folgt, findet die Pflicht nicht. + +**Belege.** `docs/issues/0040-*` (Rückmeldung), sechs AARs vom 17.–20.08. + +**Vorschlag für die nächste Iteration.** Entweder eine Prüfung, die geschlossene Vorfälle +und Deploy-Übergaben ohne zugehörigen AAR meldet — dafür bräuchte es ein maschinell +lesbares Merkmal „war ein Vorfall" am Issue. Oder die ehrliche Alternative: Wenn eine Regel +dauerhaft nur auf Nachfrage befolgt wird, ist zu prüfen, ob die Schwelle stimmt. Sechs +AARs in vier Tagen sind viel. + +--- + +## FB-02 — „Meldet Erfolg, ist aber blind" + +**Beschreibung.** Ein Schritt läuft durch, meldet Erfolg und hat nichts getan. **Sieben +belegte Vorkommen in fünf verschiedenen Werkzeugen** — ausführlich in +[docs/wiki/stolpersteine/meldet-erfolg-ist-aber-blind.md](docs/wiki/stolpersteine/meldet-erfolg-ist-aber-blind.md). + +**Ursachen-Einschätzung.** Das Verfahren verlangt verifizierbare Abnahmekriterien, aber +**nichts verlangt, dass eine selbstgebaute Prüfung einmal absichtlich rot war**. Ein Tor, +das nur grün gesehen wurde, ist eine Vermutung — genau so entstanden vier der sieben +Vorkommen. + +Zweiter Anteil: Das Muster war seit dem 2026-08-18 als solches erkannt („viertes Vorkommen" +in #0054) und stand trotzdem nur in einem Issue. Es lag nicht dort, wo `AGENTS.md` die +Lehren sucht — und wurde deshalb dreimal neu entdeckt. + +**Vorschlag.** Positivkontrolle als Pflichtbestandteil jeder neuen Prüfung: Wer ein Tor +baut, weist nach, dass es mit eingebautem Fehler rot ist. Denkbar als Gate im Design-Doc +oder als Zeile in der Abnahme. + +--- + +## FB-03 — Prüfungen erzeugen Befunde, die niemand beheben kann + +**Beschreibung.** Am 2026-08-18 waren alle geplanten Prüfungen dauerhaft rot (25 Befunde), +womit keine mehr etwas meldete. Behoben über den Quittungsmechanismus (ADR-0020). **Zwei +Tage später kam dieselbe Klasse zurück:** Der Upstream-Merge brachte 70.265 fremde Commits, +welche die Git-Hygiene-Prüfung bemängelte — Commits, die unserer Konvention nie folgen +konnten (ADR-0023). + +**Ursachen-Einschätzung.** Beim Bau einer Prüfung wird gefragt, was sie finden **soll**, +nicht, welche Befunde sie erzeugen wird, die **niemand beheben kann**. Der +Quittungsmechanismus behandelt das Symptom gut (mit Pflichtfrist), verhindert aber nicht, +dass die nächste Prüfung dieselbe Lage erzeugt. + +**Vorschlag.** Bei jeder neuen Prüfung im Voraus beantworten: *Welche Befunde wird sie +erzeugen, die strukturell nicht behebbar sind?* Wenn es welche gibt, gehört die Ausnahme in +dieselbe Änderung — nicht in eine spätere Aufräumrunde. + +--- + +## FB-04 — Issues behaupten Zustände, die längst überholt sind + +**Beschreibung.** Mehrfach an einem Tag: **#0083** nannte drei Dateien als Einzeldatei- +Mounts, die längst Verzeichnis-Mounts waren. **#0088** nannte Zahlen („13 Ingress-Regeln, +ein Egress-Vorkommen"), die nicht mehr stimmten. **#0002** führte die Firewall als Ursache, +die es nie war. **#0030** trägt im Titel „Der Restore ist nie geprobt", obwohl der +Datenbank-Restore geprobt und überwacht ist. + +**Ursachen-Einschätzung.** Issues sind append-only — richtig so, git ist die Historie. +Aber **Kopf und Titel bleiben stehen**, während die Anhänge sie widerlegen. Wer ein Issue +öffnet, liest zuerst die veraltete Fassung. Es gibt keine Pflicht, einen widerlegten Befund +im Kopf zu markieren. + +Praktische Folge, mehrfach beobachtet: Arbeit wird auf einer Prämisse begonnen, die +inzwischen falsch ist — und muss nach dem Nachmessen umgeplant werden. + +**Vorschlag.** Ein leichtgewichtiges Mittel, etwa eine `⚠️ überholt`-Zeile direkt unter dem +Titel, sobald ein Anhang die Ausgangsdiagnose widerlegt. Oder ein Feld `letzte_messung`, das +sichtbar altert. + +--- + +## FB-05 — Dashboards und Prüfungen ohne Datenbeleg + +**Beschreibung.** `dashboards/gameserver/pterodactyl-server.json` war **drei Monate +dauerhaft leer** — es fragte Metriken eines Exporters ab, der nie funktioniert hat. +Niemandem ist es aufgefallen. Dasselbe Muster beim ClamAV-Dashboard: Der Vorschlag im Issue +nutzte ein Label, das in dieser Loki gar nicht existiert. + +**Ursachen-Einschätzung.** Ein Dashboard gilt als fertig, wenn es angelegt ist. Es gibt +keine Abnahme „liefert Daten". Ein leeres Panel sieht aus wie „gerade nichts los" und ist +von „fragt Unsinn ab" nicht zu unterscheiden. + +**Vorschlag.** Abnahmekriterium für jedes neue Dashboard: Jede Query wurde gegen die +laufende Instanz geprüft und hat Daten geliefert — oder es steht dabei, warum sie +berechtigt leer ist. + +--- + +## FB-06 — Dokumente werden ergänzt, aber nicht revidiert + +**Beschreibung.** `docs/axion1337-fork.md` beschrieb nach dem Upstream-Merge weiterhin ein +Repo ohne gemeinsamen Vorfahren. `dns-soll.md` nannte einen Absender, der so nie versandte. +`monitoring/README.md` beschrieb Targets als „antworten aktuell nicht", ohne den Grund und +nach der Umstellung mit falscher Adresse. + +**Ursachen-Einschätzung.** Anhängen ist billig und fühlt sich vollständig an; das +Widerlegen einer früheren Aussage kostet Mut und Aufmerksamkeit. Beim Abschluss einer +Arbeit wird gefragt „ist es dokumentiert?", nicht „welche bestehende Aussage ist dadurch +falsch geworden?". + +**Vorschlag.** Beim Abschluss einer Arbeit ausdrücklich die Gegenfrage stellen und die +Antwort in der Abnahme festhalten — auch wenn sie „keine" lautet. + +--- + +## FB-07 — Werkzeuge messen unbemerkt die falsche Instanz + +**Beschreibung.** Über den Entwicklungstunnel zeigen `cfgmon.lab:9090` und `:3100` auf +einen **anderen** Stack (`host=dokploy-host`); der operating-Stack ist nur aus dem +matrix-Cluster über `10.0.0.3` erreichbar. Zusätzlich wird im Lab **Port 53 abgefangen** — +eine `dig`-Anfrage an eine TEST-NET-Adresse liefert ein Ergebnis. Beides hat an einem Tag +je zwei Diagnosen ins Leere laufen lassen. + +**Ursachen-Einschätzung.** Die Umgebung beantwortet Fragen, die sie nicht beantworten +kann, statt zu schweigen. Ein Werkzeug, das eine Adresse anspricht, kann nicht erkennen, +dass jemand dazwischen sitzt. Dokumentiert war das teilweise +([reference: Diagnose-Fallen](docs/wiki/admin/cfgmon.md)) — aber nicht dort, wo die +Werkzeuge laufen. + +**Vorschlag.** Gegenprobe als Standardbestandteil von Diagnose-Skripten, **vor** der +eigentlichen Messung. `pruefe-dns.sh` macht das seit dem 2026-08-20 vor; `pruefe-ports.sh` +seit dem 2026-08-19. Das Muster gehört in die Werkzeug-Vorlage, nicht in jedes Skript neu. + +--- + +*Angelegt 2026-08-20 auf Wunsch von sorb, nach einer Sitzung, in der mehrere dieser +Befunde gleichzeitig sichtbar wurden. Erstbefüllung stammt von der Seite, die die +Abweichungen verursacht hat — das ist kein Argument gegen die Befunde, aber ein Grund, +sie im Refinement gegenzulesen.* diff --git a/README.md b/README.md index a44de90..bd29dd5 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ GitLab-Issue-Template. **Alle Issues leben auf git.lab.** | [`schema.yaml`](schema.yaml) | Frontmatter-Schema — einzige Wahrheit über den Aufbau der Artefakte | | [`STATUS.md`](STATUS.md) | Generierte Übersicht; **nicht von Hand ändern** (`scripts/gen_status.py`) | | `roadmap.md` | Linien, Meilenstein-Kandidaten, Kadenz — die Gruppen-Milestones halten den Stand | +| [`FRAMEWORK-BEFUNDE.md`](FRAMEWORK-BEFUNDE.md) | Wo das Verfahren nicht getragen hat — Eingangsliste für die Framework-Ernte | | `docs/adr/` | ADRs — Pflicht bei Architektur-/Prozessentscheidungen **und dauerhaften Ausnahmen** | | `docs/issues/` | Das kanonische Backlog der ganzen Gruppe ([ADR-0012](docs/adr/0012-issues-im-repo-gitlab-als-spiegel.md), [ADR-0019](docs/adr/0019-komponenten-issues-adoptiert.md)) | | `docs/design/`, `docs/aar/` | Design-Dokumente je Vorhaben; AARs zu Vorfällen und größeren Abweichungen | diff --git a/roadmap.md b/roadmap.md index 51f0cae..92041c0 100644 --- a/roadmap.md +++ b/roadmap.md @@ -94,6 +94,9 @@ Ablauf und Timeboxes: [verfahren/refinement.md](docs/wiki/admin/refinement.md). - **AAR** nach jedem Deploy mit Übergabe und nach Incidents — offene Punkte daraus werden im selben Zug zu Issues. - **Retro light** (~monatlich, 20–30 min): Verfahren/ADRs prüfen — fasert etwas aus? + Eingangsliste dafür ist [FRAMEWORK-BEFUNDE.md](FRAMEWORK-BEFUNDE.md): + wiederkehrende Fehlerklassen und Abweichungen, die in der nächsten + neckbeard-Iteration nicht erneut passieren sollen. **Der Einstieg ist erfolgt:** [Struktur-Workshop (#17)](https://git.lab/axion1337.chat/management/-/issues/17) am 2026-08-06 — Visionen geschärft, M1–M4 angelegt, Board gesichtet, Kadenz und