do-fastted/AgentDock

Den Kreislauf durchbrechen – Tiefe Fehleranalyse

Wenn der Debug-Vorgang abgeschlossen ist, verwenden Sie dies für eine tiefgehende Analyse, um den Kreislauf "Bug reparieren -> vergessen -> wiederholen" zu durchbrechen.

---

Analyse-Rahmenwerk

Analysieren Sie den soeben behobenen Bug aus diesen 5 Dimensionen:

1. Ursachenkategorie

Zu welcher Kategorie gehört dieser Bug?

Kategorie	Merkmale	Beispiel
A. Fehlende Spezifikation	Keine Dokumentation, wie es gemacht werden soll	Neue Funktion ohne Checkliste
B. Schnittstellenvertrag zwischen Schichten	Schnittstelle zwischen Schichten unklar	API gibt anderes Format zurück als erwartet
C. Fehlerhafte Änderungsweitergabe	Eine Stelle geändert, andere vergessen	Funktionssignatur geändert, Aufrufstellen vergessen
D. Testlücke	Unit-Test bestanden, Integrationstest fehlgeschlagen	Funktioniert allein, bricht in Kombination
E. Implizite Annahme	Code basiert auf undokumentierter Annahme	Zeitstempel in Sekunden vs. Millisekunden

2. Warum Fixes fehlschlugen (falls zutreffend)

Wenn Sie vor dem endgültigen Fix mehrere erfolglose Versuche unternommen haben, analysieren Sie jeden Fehlschlag:

• Oberflächlicher Fix: Symptom behoben, nicht die Ursache
• Unvollständiger Umfang: Ursache gefunden, aber nicht alle Fälle abgedeckt
• Werkzeuglimitierung: grep hat es übersehen, Typprüfung war nicht streng genug
• Denkmodell: Immer in derselben Schicht gesucht, nicht schichtübergreifend gedacht

3. Präventionsmechanismen

Welche Mechanismen würden verhindern, dass dies erneut auftritt?

Typ	Beschreibung	Beispiel
Dokumentation	Aufschreiben, damit Bescheid wissen	Denk-Leitfaden aktualisieren
Architektur	Fehler strukturell unmöglich machen	Typsichere Wrapper
Kompilierung	Strenge Typprüfung, keine Notlösungen	Signaturänderung verursacht Kompilierungsfehler
Laufzeit	Überwachung, Alarme, Scans	Verwaiste Entitäten erkennen
Testabdeckung	E2E-Tests, Integrationstests	Vollständigen Ablauf verifizieren
Code-Review	Checkliste, PR-Vorlage	"Haben Sie X überprüft?"

4. Systematische Erweiterung

Welche breiteren Probleme deckt dieser Bug auf?

• Ähnliche Probleme: Wo sonst könnte dieses Problem bestehen?
• Designfehler: Gibt es ein grundlegendes Architekturproblem?
• Prozessfehler: Gibt es eine Verbesserung im Entwicklungsprozess?
• Wissenslücke: Fehlt dem Team ein bestimmtes Verständnis?

5. Wissenssicherung

Erkenntnisse im System verankern:

• Denkleitfäden in .trellis/spec/guides/ aktualisieren
• relevante .trellis/spec/-Dokumente aktualisieren
• Issue-Eintrag erstellen (falls zutreffend)
• Feature-Ticket für grundlegenden Fix erstellen
• Prüfrichtlinien bei Bedarf aktualisieren

---

Ausgabeformat

Bitte geben Sie die Analyse in diesem Format aus:

## Bug-Analyse: [Kurzbeschreibung]

### 1. Ursachenkategorie
- **Kategorie**: [A/B/C/D/E] - [Kategoriename]
- **Spezifische Ursache**: [Detaillierte Beschreibung]

### 2. Warum Fixes fehlschlugen (falls zutreffend)
1. [Erster Versuch]: [Warum er fehlschlug]
2. [Zweiter Versuch]: [Warum er fehlschlug]
...

### 3. Präventionsmechanismen
| Priorität | Mechanismus | Spezifische Maßnahme | Status |
|-----------|-------------|----------------------|--------|
| P0 | ... | ... | TODO/DONE |

### 4. Systematische Erweiterung
- **Ähnliche Probleme**: [Liste von Stellen mit ähnlichen Problemen]
- **Designverbesserung**: [Architekturvorschläge]
- **Prozessverbesserung**: [Vorschläge zum Entwicklungsprozess]

### 5. Wissenssicherung
- [ ] [Zu aktualisierende Dokumente / zu erstellende Tickets]

---

Kernphilosophie

Der Wert des Debuggens liegt nicht im Beheben des Bugs, sondern darin, dass diese Klasse von Bugs nie wieder auftritt.

Drei Ebenen der Erkenntnis:

1. Taktisch: Wie man DIESEN Bug behebt
2. Strategisch: Wie man DIESE KLASSE von Bugs verhindert
3. Philosophisch: Wie man Denkmuster erweitert

30 Minuten Analyse sparen 30 Stunden zukünftiges Debugging.

Denkrahmen: Bayessches Denken

Wenn mehrere Ursachen plausibel sind und Belege unvollständig sind, aktualisieren Sie Ihre Überzeugungen proportional zu neuen Beweisen, anstatt an Anfangshypothesen festzuhalten.

Schritt 1: A-priori-Wahrscheinlichkeiten festlegen

Geben Sie vor der Untersuchung an, was Sie glauben und warum:

Hypothese	Prior	Begründung
H1: [Ursache A]	40%	Am häufigsten bei diesem Muster
H2: [Ursache B]	30%	Angesichts der Umgebung plausibel
H3: [andere]	30%	Sammelposten

A-priori-Werte müssen 100 % ergeben. Wenn Sie keine Wahrscheinlichkeiten zuweisen können, untersuchen Sie zuerst.

Schritt 2: Beweise beobachten

Dokumentieren Sie, was Sie gefunden haben — seien Sie genau bezüglich der Zuverlässigkeit:

• Was genau haben Sie beobachtet?
• Wie zuverlässig? (Testausgabe > Logmeldung > Benutzerbericht > Bauchgefühl)
• Könnten mehrere Hypothesen dies erklären?

Schritt 3: Überzeugungen aktualisieren

Fragen Sie für jede Hypothese: Wie wahrscheinlich sind diese Beweise, wenn diese Hypothese wahr wäre?

Die Richtung der Änderung ist wichtiger als die Berechnung:

• Von H1 stark vorhergesagte Beweise → Wahrscheinlichkeit von H1 steigt
• Mit H2 widersprüchliche Beweise → Wahrscheinlichkeit von H2 sinkt
• Unter allen Hypothesen gleich wahrscheinliche Beweise → keine Aktualisierung

Schritt 4: Diskriminierende Beweise suchen

Sammeln Sie nicht mehr vom Selben. Finden Sie Beweise, die sich stark zwischen den Top-Hypothesen unterscheiden.

Wenn H1 und H3 nahe beieinander liegen: "Was würde ich sehen, wenn H1 wahr wäre, aber nicht wenn H3 wahr wäre?" Dann darauf prüfen.

Schritt 5: Konfidenz angeben

Konfidenz	Aktion
90 %+	Mit Fix fortfahren, überwachen
70–90 %	Fortfahren, Fallback-Prüfung hinzufügen
50–70 %	Hypothese vor dem Commit testen
<50 %	Mehr Beweise nötig, keine Vermutungen anstellen

Drücken Sie niemals binäre Sicherheit aus, wenn die Beweislage unvollständig ist. Verwenden Sie "höchstwahrscheinlich", "plausibel aber unwahrscheinlich", "untersuchenswert".

Häufige Denkfehler

Fehler	Beispiel	Korrektur
Vernachlässigung der Basisrate	"Test fehlgeschlagen → Code ist kaputt"	Wie oft schlagen Tests aus anderen Gründen fehl?
Bestätigungsfehler	"Das muss eine Race Condition sein, lass mich Beweise für Race finden"	Suchen Sie aktiv nach Beweisen GEGEN Ihre Top-Hypothese
Ankereffekt	"Letztes Mal war es Caching, wahrscheinlich wieder Caching"	Legen Sie A-priori-Werte aus dem aktuellen Kontext fest, nicht aus dem Bug von gestern

---

Nach der Analyse: Sofortige Maßnahmen

WICHTIG: Nach Abschluss der obigen Analyse MÜSSEN Sie sofort:

1. spec/guides aktualisieren – Listen Sie nicht nur TODOs auf, sondern aktualisieren Sie tatsächlich die relevanten Dateien:

   • Wenn es ein plattformübergreifendes Problem ist → cross-platform-thinking-guide.md aktualisieren
   • Wenn es ein schichtübergreifendes Problem ist → cross-layer-thinking-guide.md aktualisieren
   • Wenn es ein Problem der Code-Wiederverwendung ist → code-reuse-thinking-guide.md aktualisieren
   • Wenn es domänenspezifisch ist → backend/*.md oder frontend/*.md aktualisieren

2. Vorlagen synchronisieren – Nach der Aktualisierung von .trellis/spec/ mit src/templates/markdown/spec/ abgleichen

3. Die Spezifikationsaktualisierungen committen – Dies ist die primäre Ausgabe, nicht nur der Analysetext

Die Analyse ist wertlos, wenn sie im Chat bleibt. Der Wert liegt in den aktualisierten Spezifikationen.