deep-debugging

by brasco05

Install this Skill

curl -fsSL -o deep-debugging.zip https://skill.seembox.com/api/v1/skills/deep-debugging/download && unzip deep-debugging.zip

Download deep-debugging.zip

SKILL.md About

---
name: deep-debugging
description: Systematic evidence-first debugging for unclear, recurring, or high-risk software bugs. Use when the user asks to debug/root-cause an issue, says a fix did not work, reports 401/403/500 with context, or needs investigation before changing code. Do not use for obvious typos, missing installs, or trivial config fixes.
---

# Deep Debugging Skill

**Kein blindes Fixen. Kein Raten. Erst beweisen, dann lösen.**

## Trigger-Wörter (Skill sofort laden)

Dieser Skill wird **sofort aktiviert** wenn der User eines dieser Wörter schreibt:
- `debug`, `debugg`, `debugge`, `debugging`
- `bug`, `bugfix`, `buggy`
- `broken`, `kaputt`, `funktioniert nicht`
- `fehler`, `error`, `crash`, `absturz`
- `schlägt fehl`, `wirft error`, `wirft exception`
- `401`, `403`, `500` (direkt als Nachricht)

---

## Wenn du diesen Skill liest: STOPP.

Leg alle Fix-Ideen beiseite. Du wirst NICHTS ändern bevor du die Ursache zu 100% kennst.

---

## PRE-PHASE — Quick Triage (30 Sekunden, IMMER zuerst)

Bevor du irgendwas analysierst — diese 5 Dinge in 30 Sekunden prüfen:

```
□ Server neu gestartet nach letzter Änderung?
□ ENV-Variablen korrekt gesetzt (auch in .env.local)?
□ npm install / yarn nach Package-Änderungen ausgeführt?
□ Datenbank-Migration gelaufen? (npx prisma migrate dev)
□ Browser-Cache geleert / Hard Reload (Ctrl+Shift+R)?
```

**Wenn eines davon "Nein" → erst das fixen, dann weiter.**
Wenn alle "Ja" → weiter zu Phase 1.

---

## PHASE 1 — Daten sammeln (nur beobachten, nichts anfassen)

Beantworte diese 4 Fragen mit echten Beweisen aus Logs/Code:

### 1. Was genau passiert?
- Exakte Fehlermeldung oder Stack Trace aus den Logs
- HTTP Status Code (401? 403? 500? Redirect?)
- Welcher Endpoint / welche Funktion / welcher Service ist betroffen
- Was sieht der User vs. was passiert im Backend

### 2. Wann passiert es?
- Immer oder nur manchmal?
- Nur bei bestimmten Usern / Rollen / Inputs?
- Seit wann — nach welchem Commit / welcher Änderung?
- Reproduzierbar in welchen Schritten genau?

### 3. Was sollte stattdessen passieren?
- Erwartetes Verhalten klar in einem Satz benennen
- Tatsächliches Verhalten klar in einem Satz benennen

### 4. Was wurde zuletzt geändert?
- Letzter relevanter Commit
- Neue ENV-Variablen, neue Abhängigkeiten, neue Migrationen?

**→ STOPP. Erst wenn alle 4 Fragen beantwortet sind: weiter zu Phase 2.**

---

## PHASE 2 — Hypothese aufstellen (PFLICHT)

Formuliere EINE konkrete, testbare Hypothese bevor du irgendetwas anfasst:

```
"Der Fehler tritt auf weil [konkrete Ursache],
was ich beweise/widerlege indem ich [konkreter Test]."
```

**Gute Hypothese:**
```
"Der User wird rausgeworfen weil das JWT nach dem Login nicht 
korrekt im Cookie gesetzt wird, was ich beweise indem ich 
den Set-Cookie Header in der Login-Response in den Backend 
Logs überprüfe."
```

**Schlechte Hypothese:**
```
"Irgendwas stimmt mit der Auth nicht."
→ Zu vage. Nochmal. Konkrete Ursache benennen.
```

**Melde die Hypothese bevor du weitermachst.**
Format: `🔬 HYPOTHESE: [deine Hypothese]`

---

## Hypothese → Checkliste-Selector

Anhand der Hypothese die passende Checkliste in Phase 3 auswählen:

| Hypothese betrifft | Checkliste in Phase 3 |
|---|---|
| Auth / Login / Token / Session | **Auth-Bug** (JWT-Flow, Schritt 1–5) |
| API / Request / Response / CORS | **API-Bug** (Request-Kette) |
| UI / Render / State / Hooks | **Frontend-Bug** (React/Next.js) |
| DB / Schema / Query / Migration | **DB-Bug** (Prisma/TypeORM) |
| Speed / Memory / Bundle / Render-Performance | **Performance** |

---

## PHASE 3 — Binary Search (Fehler eingrenzen)

Teile das Problem in zwei Hälften. Teste eine Hälfte.
- Liegt der Fehler dort → weiter aufteilen
- Liegt er nicht dort → andere Hälfte testen

### Für Auth/Session-Bugs (häufigster Fall):
```
Schritt 1: Login-Request → wird JWT korrekt generiert?
 → Logs: POST /auth/login → 200 oder Fehler?

Schritt 2: JWT im Response → landet er korrekt beim Client?
 → Set-Cookie Header vorhanden? LocalStorage befüllt?

Schritt 3: Folge-Request → wird JWT mitgeschickt?
 → Authorization: Bearer [token] im Request-Header? Cookie present?

Schritt 4: Guard/Middleware → wird JWT korrekt validiert?
 → JwtAuthGuard wirft 401? Welche Fehlermeldung?

Schritt 5: JWT-Signing-Konfiguration → ist sie in Modul und Strategy identisch? Werte niemals ausgeben.
 → Gleicher Signing key beim Generieren (JwtModule) und Validieren (JwtStrategy)?
```

### Für allgemeine API-Bugs:
```
Request rein → Middleware → Guard → Controller → Service → DB → Response
     ↑              ↑          ↑         ↑           ↑
     Wo bricht die Kette? Jeden Schritt einzeln testen.
```

### Für Frontend-Bugs (React/Next.js):
```
User-Action → Event Handler → State-Update → Re-render → API-Call → Response → UI-Update
     ↑               ↑              ↑             ↑           ↑          ↑
     Wo bricht die Kette?

Checkliste:
□ Console.log DIREKT nach dem Event: kommt die Action überhaupt an?
□ State korrekt? (React DevTools → Components → State inspizieren)
□ useEffect dependencies richtig? (zu wenige → stale closure, zu viele → infinite loop)
□ API-Call: Network Tab → Request Payload korrekt? Response korrekt?
□ Hydration Error: passiert nur SSR? Client-only Code in Server Component?
□ Keys fehlen in Liste? → React warnt, aber rendert falsch
□ Async State: wird State gesetzt bevor Component unmounted?
```

### Für Datenbank-Bugs (Prisma/TypeORM):
```
□ Schema stimmt mit Migration überein? → prisma db push oder migrate dev
□ Fehlende Relation: include/join vergessen?
□ Null-Safety: Feld optional aber kein null-check?
□ Transaction abgebrochen: welcher Teil schlägt fehl?
□ Connection Pool erschöpft: zu viele offene Connections?

Prisma Debug-Modus aktivieren:
const prisma = new PrismaClient({ log: ['query', 'error', 'warn'] })
→ Zeigt jeden SQL-Query mit Parametern
```

### Für Performance-Bugs:
```
□ N+1 Problem: wird in einer Schleife jedes Mal eine DB-Query gemacht?
□ Missing Index: EXPLAIN ANALYZE auf den langsamen Query
□ Re-renders: React DevTools Profiler → was rendert unnötig?
□ Bundle Size: next build → welche Packages sind zu groß?
□ Memory Leak: Interval/EventListener nicht aufgeräumt bei unmount?
```

**Melde nach jeder Testphase:**
- ✅ [Schritt X] OK — Fehler liegt nicht hier
- ❌ [Schritt X] FEHLER GEFUNDEN — [was genau]

---

## PHASE 4 — Fix (erst jetzt)

Nur wenn die Ursache durch Phase 1-3 bewiesen ist:

1. **Minimalen Fix implementieren** — nur das was den Fehler behebt, nichts anderes
2. **Nicht gleichzeitig refactoren** — ein Problem, ein Fix
3. **Direkt testen** ob der spezifische Fehler weg ist
4. **Verification** ausführen bevor "fertig" gemeldet wird

---

## Häufige Fehlerquellen (NestJS/Next.js-Stack)

| Symptom | Zuerst prüfen |
|---|---|
| User wird nach Login rausgeworfen | JWT-Signing-Konfiguration unterscheidet sich zwischen Modul und Strategy, Cookie SameSite/Secure Settings, CORS-Config |
| HTTP 401 bei authentifizierten Requests | JWT expired, falscher Signing key, Bearer Token fehlt im Header, `validate()` wird nicht aufgerufen |
| HTTP 403 | Rolle fehlt, Guard-Logik prüfen, Tenant-Isolation blockiert |
| HTTP 500 ohne Stack Trace | Unbehandelte Promise-Rejection, console.error in Logs suchen |
| "Cannot read property of undefined" | Null-checks fehlen, DB-Query gibt null zurück |
| Route nicht gefunden (404) | Module nicht in AppModule importiert, falscher Controller-Prefix, Global-Prefix-Dopplung (api/api/) |
| DB-Fehler beim Start | Migration nicht ausgeführt, Spalte existiert nicht, ENV-Variable fehlt |
| Cookie wird nicht gesetzt | SameSite=None + Secure=true nötig bei Cross-Origin; SameSite=Lax für same-site |
| Cookie wird nicht mitgeschickt | Cross-Origin Fetch braucht `credentials: 'include'`, Next.js Rewrites funktionieren nur SSR-seitig |
| JWT Strategy extrahiert Token aber 401 | JWT Strategy signing configuration differs from JwtModule configuration |
| Hydration Error (Next.js) | Client-only API (window/localStorage) in Server Component, Date/Math.random() Mismatch |
| Infinite Re-render Loop | useEffect dependency array falsch, State-Update in Render-Funktion |
| "React Hook called conditionally" | useState/useEffect NACH einem Early Return — alle Hooks VOR Early Returns |
| Prisma: "Unknown field" | Schema geändert aber kein `prisma generate` ausgeführt |
| CORS Error trotz CORS-Config | Preflight OPTIONS-Request nicht behandelt, Origin-Whitelist unvollständig |

---

## Debugging-Tools

### NestJS Backend
```bash
# Live-Logs mit tee
npm run start:dev 2>&1 | tee /tmp/backend-debug.log

# JWT Claims prüfen, ohne Token-Werte zu speichern oder auszugeben
# Nur mit lokalem Test-Token und nur die nicht-sensiblen Claim-Namen notieren.
node -e "const t=process.env.TEST_JWT; if(!t) throw new Error('TEST_JWT missing'); const p=JSON.parse(Buffer.from(t.split('.')[1], 'base64url')); console.log(Object.keys(p))"

# Login + /me curl-Test nur mit lokalen Test-Credentials.
# Keine echten Passwörter, Cookies oder Tokens in Logs/Reports kopieren.
curl -X POST http://localhost:4000/api/auth/login \
  -H 'Content-Type: application/json' \
  -d @local-test-login-payload.json \
  -c /tmp/app-debug-cookies.txt -s -o /tmp/app-debug-login.out -w "%{http_code}\n"

curl http://localhost:4000/api/auth/me \
  -b /tmp/app-debug-cookies.txt -s -o /tmp/app-debug-me.out -w "%{http_code}\n"
```

### Prisma
```bash
# DB-Status prüfen. Keine Produktionsdaten oder Connection Strings in Reports kopieren.
npx prisma migrate status

# Schema-Vergleich nur nach expliziter Zustimmung, weil er lokale Prisma-Dateien ändern kann.
# npx prisma db pull
```

### React / Next.js
```bash
# Build-Fehler analysieren
next build 2>&1 | grep -E "Error|Warning"

# Bundle-Größe analysieren
ANALYZE=true next build  # mit @next/bundle-analyzer

# TypeScript-Fehler finden
tsc --noEmit
```

### Allgemein
```bash
# Letzten Commit der eine Datei geändert hat
git log --oneline --follow -p -- src/auth/jwt.strategy.ts | head -50

# Wann hat ein Bug angefangen? Binary search in Git
git bisect start
git bisect bad HEAD
git bisect good [letzter-funktionierender-commit]
```

---

## Reporting-Format (PFLICHT nach jedem Debugging)

```
🔍 DEBUG REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Fehler: [Exakte Fehlermeldung aus Logs]
Lokalisiert: [Datei:Zeile / Funktion / Service]
Ursache: [Was wirklich passiert ist — eine klare Erklärung]
Beweis: [Wie die Ursache bewiesen wurde]
Fix: [Was genau geändert wurde — Datei + was]
Verifiziert: [Ja — wie getestet, welcher Test grün]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Absolute Regeln

- **NIEMALS** fixen ohne Hypothese aus Phase 2
- **NIEMALS** mehrere Dinge gleichzeitig ändern
- **NIEMALS** "probieren ob es hilft" — nur beweisbasierte Fixes
- **NIEMALS** Phase überspringen weil der Fix "offensichtlich" wirkt
- Wenn nach 3 Fix-Versuchen der Bug noch existiert → Eskalations-Pfad (siehe unten)
- **Scope-Disziplin:** Nur den gemeldeten Bug fixen, keine anderen Baustellen anfassen

### Eskalations-Pfad nach 3 Fehlversuchen

Nicht zurück zu Phase 1 — das ist eine Sackgasse wenn Phase 1 korrekt war. Stattdessen:

**Schritt 1 — Status-Bericht erstellen:**
```
Aktuelle Hypothese: [was zuletzt angenommen wurde]
Getestet: [was konkret geprüft/geändert wurde, Versuch 1–3]
Ergebnis: [was bei jedem Versuch rausgekommen ist]
Offen: [welche Hypothesen noch nicht ausgeschlossen wurden]
```

**Schritt 2 — User aktiv einbinden:**

> "Ich habe 3 Versuche ohne Erfolg. Folgende Hypothesen sind noch offen:
> 1. [Hypothese A]
> 2. [Hypothese B]
> 3. [Hypothese C]
> Welche soll ich tiefer verfolgen — oder gibt es neuen Kontext den ich nicht habe?"

**Schritt 3 — Optional: Frischer Subagent (bei kontaminiertem Reasoning-Path):**

Wenn die bisherigen Versuche möglicherweise den eigenen Reasoning-Path verzerrt haben, einen neuen Subagent mit minimalem Kontext spawnen:
- Nur Fehlermeldung + relevante Code-Stellen mitgeben
- Keine bisherigen Hypothesen vorab nennen (verhindert Confirmation Bias)
- Ergebnisse des Subagents mit eigenem Stand abgleichen

---

## Lessons Learned (aus echten Bugs)

### JWT Signing key Mismatch (2026-03-19)
**Symptom:** User wird nach Login sofort rausgeworfen, `/auth/me` gibt 401

**Falle:** `JwtModule.register()` und `JwtStrategy` verwendeten unterschiedliche Signing-Konfigurationen.

**Beweis-Methode:** Lokale Debug-Logs ohne Signing-Werte → Strategy erreicht `validate()` nicht → Signatur-Verifikation schlägt fehl → Signing-Konfiguration stimmt nicht überein.

**Fix:** Signing-Konfiguration zentralisieren, sodass Token-Erzeugung und Verifikation dieselbe Quelle verwenden. Keine realen Signing-Werte in Logs, Reports oder Beispielen zeigen.

### Cross-Origin Cookie Problem (2026-03-19)
**Symptom:** Login erfolgreich, aber alle API-Calls geben 401

**Falle:** `fetch()` vom Browser sendet Cookies **NICHT** bei Cross-Origin-Requests (localhost:3000 → localhost:4000), auch wenn `credentials: 'include'` gesetzt ist und Next.js Rewrites konfiguriert sind.

**Warum Next.js Rewrites nicht helfen:** Rewrites funktionieren nur für **SSR-seitige** Requests, nicht für client-side `fetch()`.

**Fix:** Sicherstellen dass alle API-Calls über die **gleiche Origin** laufen (Next.js als Proxy) ODER JWT auch im Response-Body zurückgeben und im `Authorization` Header senden.

### NestJS Controller-Prefix-Dopplung (2026-03-21)
**Symptom:** API-Endpoint gibt 404, obwohl Controller und Route korrekt aussehen

**Falle:** Global Prefix `api` + Controller-Pfad `api/something` → `/api/api/something` → 404

**Fix:** Controller-Pfad niemals mit `api/` prefixen. Nur den Ressourcennamen:
```typescript
@Controller('users')  // ✅ → /api/users
@Controller('api/users')  // ❌ → /api/api/users
```

### React Rules of Hooks Violation (2026-03-22)
**Symptom:** "React Hook useState is called conditionally" Error, App crasht

**Falle:** `useState` oder `useEffect` nach einem Early Return:
```typescript
if (!user) return null  // ← Early Return
const [data, setData] = useState([])  // ← Hook DANACH → Fehler!
```

**Fix:** Alle Hooks VOR jeden Early Return verschieben:
```typescript
const [data, setData] = useState([])  // ← Erst Hooks
if (!user) return null  // ← Dann Early Return
```

### req.user.id vs req.user.sub (2026-03-22)
**Symptom:** `req.user.id` ist `undefined` in NestJS Controller, obwohl JWT korrekt

**Falle:** JWT-Standard speichert die User-ID in `sub`, nicht in `id`. NestJS JwtStrategy gibt das decoded JWT payload zurück — also `sub`, nicht `id`.

**Fix:** Immer `req.user.sub` statt `req.user.id` in NestJS-Controllern:
```typescript
@Get('me')
getMe(@Request() req) {
  return this.usersService.findOne(req.user.sub)  // ✅
}
```

### Prisma N+1 Query bei nested includes (2026-04-28)
**Symptom:** Endpoint wird mit wachsender Datenmenge immer langsamer; bei 100 Einträgen dauert eine List-Anfrage 3–8 Sekunden. Einzelne Einträge sind schnell.

**Falle:** Eine Schleife über die Hauptentität macht pro Iteration eine eigene DB-Query für eine verknüpfte Relation — obwohl Prisma `include` angeboten hätte:
```typescript
// ❌ N+1: 1 Query für Patienten + N Queries für jeweils deren Termine
const patients = await prisma.patient.findMany()
for (const p of patients) {
  p.appointments = await prisma.appointment.findMany({ where: { patientId: p.id } })
}
```

**Beweis-Methode:** Prisma Query-Logging aktivieren:
```typescript
const prisma = new PrismaClient({ log: ['query'] })
```
Im Log erscheinen bei 50 Patienten genau 51 SELECT-Statements statt einem.

**Fix:** Relation direkt im `findMany`-Aufruf per `include` mitladen — Prisma batched das in eine optimierte Abfrage:
```typescript
// ✅ Ein Query, alle Relationen geladen
const patients = await prisma.patient.findMany({
  include: { appointments: true }
})
```
Bei tief verschachtelten Relationen `select` statt `include` nutzen um nur benötigte Felder zu laden und Payload-Größe zu kontrollieren.

_meta.json Metadata

{
  "ownerId": "kn7707zn5z1t2d8sjtmhhkwcan83vs6a",
  "publishedAt": 1778141487313,
  "slug": "deep-debugging",
  "version": "1.0.5"
}