kaizen

1. Continuous Improvement (Kaizen)

Kleine, inkrementelle Aenderungen statt Big Bang Refactoring.

Prinzip: Jeder Commit sollte den Code minimal besser hinterlassen als vorgefunden.

```typescript

// VORHER: Grosses Refactoring geplant

// "Ich refactore mal schnell die ganze Auth-Logik"

// KAIZEN: Kleine Schritte

// Commit 1: Extrahiere validateToken() aus auth.ts

// Commit 2: Fuege Typen fuer TokenPayload hinzu

// Commit 3: Ersetze any mit unknown + Type Guard

// Commit 4: Schreibe Unit Test fuer validateToken()

```

2. Poka-Yoke (Error Proofing)

Fehler durch Design verhindern, nicht durch Disziplin.

TypeScript Constraints:

```typescript

// FALSCH: Runtime Check (Fehler moeglich)

function processOrder(status: string) {

if (status !== 'pending' && status !== 'approved') {

throw new Error('Invalid status');

}

}

// POKA-YOKE: Compile-Time Constraint (Fehler unmoeglich)

type OrderStatus = 'pending' | 'approved' | 'shipped' | 'cancelled';

function processOrder(status: OrderStatus) {

// TypeScript verhindert ungueltige Werte

}

```

Fail-Fast Pattern:

```typescript

// FALSCH: Spaete Fehlererkennung

async function analyzeData(file: File) {

const data = await parseFile(file); // 10 Sekunden

const result = await geminiAnalyze(data); // 30 Sekunden

if (!data.hasRequiredColumns()) { // Fehler erst nach 40 Sekunden!

throw new Error('Missing columns');

}

}

// POKA-YOKE: Fail-Fast (fruehe Validierung)

async function analyzeData(file: File) {

// Validierung ZUERST (< 1ms)

const preview = await parseFilePreview(file, 10);

if (!preview.hasRequiredColumns()) {

throw new Error('Missing columns'); // Sofort!

}

// Teure Operationen NUR wenn valide

const data = await parseFile(file);

const result = await geminiAnalyze(data);

}

```

3. Standardized Work

Konsistente Patterns reduzieren kognitive Last und Fehler.

API Response Pattern (fabrikIQ Standard):

```typescript

// Standard Response Format

interface ApiResponse {

success: boolean;

data?: T;

error?: {

code: string;

message: string;

details?: unknown;

};

meta?: {

timestamp: string;

duration_ms: number;

region: 'fra1'; // DSGVO

};

}

// Alle Endpoints nutzen dieses Format

export async function handler(req: Request): Promise {

const start = Date.now();

try {

const result = await processRequest(req);

return Response.json({

success: true,

data: result,

meta: {

timestamp: new Date().toISOString(),

duration_ms: Date.now() - start,

region: 'fra1'

}

});

} catch (error) {

return Response.json({

success: false,

error: {

code: error.code ?? 'UNKNOWN_ERROR',

message: error.message

}

}, { status: error.status ?? 500 });

}

}

```

4. Just-In-Time (YAGNI)

Implementiere nur was JETZT gebraucht wird.

```typescript

// FALSCH: "Vielleicht brauchen wir das spaeter"

interface User {

id: string;

email: string;

name: string;

// "Fuer spaeter"

avatar?: string;

preferences?: UserPreferences;

notifications?: NotificationSettings;

integrations?: ExternalIntegrations;

analytics?: UserAnalytics;

}

// YAGNI: Nur aktuelle Requirements

interface User {

id: string;

email: string;

name: string;

}

// Erweitern wenn tatsaechlich benoetigt (mit eigenem Commit)

```

---

/why - 5-Whys Root Cause Analysis

Trigger: /why, 5 whys, root cause, warum passiert

Anwendung: Bei Bugs, Production Incidents, wiederkehrenden Problemen

Workflow:

1. Problem definieren (konkret, messbar)

```

Problem: API Timeout bei SECOM-Dataset (504 nach 60s)

```

1. 5x "Warum?" fragen

```

Why 1: Warum Timeout?

→ Gemini API braucht >60s fuer Antwort

Why 2: Warum >60s?

→ Prompt enthaelt 590 Spalten x 1567 Zeilen

Why 3: Warum so viele Daten?

→ Kein Column Sampling implementiert

Why 4: Warum kein Sampling?

→ Urspruenglich nur kleine CSVs erwartet

Why 5: Warum nicht angepasst?

→ Keine automatischen Performance-Tests mit grossen Dateien

```

1. Root Cause identifizieren

```

Root Cause: Fehlende Performance-Testabdeckung fuer grosse Datasets

```

1. Countermeasure definieren

```

Massnahme 1: Column Sampling (MAX_COLUMNS = 50) implementieren

Massnahme 2: Performance-Test mit SECOM in CI/CD hinzufuegen

Massnahme 3: Timeout-Monitoring mit Alerting einrichten

```

Output-Format:

```markdown

Problem: [Konkrete Beschreibung]

Datum: [ISO-8601]

Betroffene Komponente: [Datei/Service]

Analyse

| Level | Frage | Antwort |

|-------|-------|---------|

| Why 1 | Warum [Symptom]? | [Antwort] |

| Why 2 | Warum [Antwort 1]? | [Antwort] |

| Why 3 | Warum [Antwort 2]? | [Antwort] |

| Why 4 | Warum [Antwort 3]? | [Antwort] |

| Why 5 | Warum [Antwort 4]? | [Antwort] |

Root Cause

[Kernursache in einem Satz]

Countermeasures

1. Sofort (< 1 Tag): [Quick Fix]
2. Kurzfristig (< 1 Woche): [Strukturelle Loesung]
3. Langfristig (< 1 Monat): [Praevention]

```

---

/cause-and-effect - Ishikawa Diagram

Trigger: /cause-and-effect, /ishikawa, /fishbone, ursache-wirkung

Anwendung: Bei komplexen Problemen mit mehreren moeglichen Ursachen

Die 6 M-Kategorien (Manufacturing):

1. Mensch (People): Skills, Training, Kommunikation
2. Maschine (Machine): Hardware, Tools, Infrastructure
3. Material (Material): Input-Daten, Dependencies
4. Methode (Method): Prozesse, Workflows, Patterns
5. Messung (Measurement): Monitoring, Tests, Metriken
6. Milieu (Environment): Production, Staging, Local

Workflow:

1. Effekt definieren (rechts)

```

Effekt: Login schlaegt intermittierend fehl

```

1. Ursachen nach Kategorie sammeln

```

MENSCH:

├── Nutzer loescht Cookies manuell

└── Admin aendert Session-TTL ohne Kommunikation

MASCHINE:

├── Vercel Cold Start > Session Check

└── KV Storage Latenz-Spikes

MATERIAL:

├── JWT Secret Rotation nicht synchron

└── OAuth Token abgelaufen

METHODE:

├── Kein Retry bei Session-Validierung

└── Keine Graceful Degradation

MESSUNG:

├── Keine Login-Erfolgsrate-Metrik

└── Kein Alerting bei Auth-Fehlern

MILIEU:

├── Production vs Preview unterschiedliche KV

└── Lokale Entwicklung ohne echte Auth

```

1. Wahrscheinlichste Ursachen priorisieren

1. Validierung planen (Hypothesen testen)

Output-Format:

```

┌─────────────────────────────────────────────────────┐

│ │

┌───────────┐ │ ┌───────────┐ ┌───────────┐ │

│ MENSCH │───┼───│ MASCHINE │ │ MATERIAL │────────────────┤

└───────────┘ │ └───────────┘ └───────────┘ │

│ │ │ │ │

┌────┴────┐ │ ┌────┴────┐ ┌────┴────┐ │

│ Cookies │ │ │ Cold │ │ JWT │ ▼

│ geloescht│ │ │ Start │ │ Rotation│ ┌──────────────┐

└─────────┘ │ └─────────┘ └─────────┘ │ LOGIN │

│ │ FEHLER │

┌───────────┐ │ ┌───────────┐ ┌───────────┐ └──────────────┘

│ METHODE │───┼───│ MESSUNG │ │ MILIEU │────────────────┤

└───────────┘ │ └───────────┘ └───────────┘ │

│ │ │ │ │

┌────┴────┐ │ ┌────┴────┐ ┌────┴────┐ │

│ Kein │ │ │ Keine │ │ Prod vs │ │

│ Retry │ │ │ Alerting│ │ Preview │ │

└─────────┘ │ └─────────┘ └─────────┘ │

│ │

└─────────────────────────────────────────────────────┘

| # | Kategorie | Ursache | Wahrscheinlichkeit | Validierung |

|---|-----------|---------|-------------------|-------------|

| 1 | Maschine | Cold Start | Hoch | Logs auf "first request" pruefen |

| 2 | Material | JWT Rotation | Mittel | Secret-Aenderungshistorie pruefen |

| 3 | Methode | Kein Retry | Mittel | Retry-Logik implementieren, messen |

```

---

/plan-do-check-act - PDCA Zyklus

Trigger: /pdca, /plan-do-check-act, deming cycle, verbesserungszyklus

Anwendung: Bei Feature-Implementierung, Refactoring, Process Improvement

Workflow:

```

┌─────────────────────┐

│ │

│ ┌─────┐ ───────► ┌─────┐

│ │PLAN │ │ DO │

│ └─────┘ ◄─────── └─────┘

│ ▲ │

│ │ ▼

│ ┌─────┐ ┌─────┐

│ │ ACT │ ◄─────── │CHECK│

│ └─────┘ └─────┘

│ │

└─────────────────────┘

(Iterate)

```

Phase 1: PLAN

• Ziel definieren (SMART: Specific, Measurable, Achievable, Relevant, Time-bound)
• Hypothese formulieren
• Erfolgskriterien festlegen
• Risiken identifizieren

```markdown

Ziel: API Response Time < 10s fuer 95% der Requests (aktuell: 30s)

Deadline: 2025-01-15

Hypothese: Column Sampling auf 50 Spalten reduziert Tokens um 80%

Erfolgskriterien:

• [ ] P95 Latency < 10s
• [ ] Keine Qualitaetsverlust in Analyse-Output
• [ ] SECOM-Dataset funktioniert ohne Timeout

Risiken:

• Sampling koennte wichtige Spalten ausschliessen
• Nutzer erwarten alle Spalten in Analyse

```

Phase 2: DO

• Implementierung in kleinen Schritten
• Dokumentation waehrend der Umsetzung
• Isolierte Aenderungen (Feature Branch)

```markdown

Branch: feature/column-sampling

Commits:

1. feat: add MAX_COLUMNS constant (50)
2. feat: implement column sampling in fileParser
3. test: add SECOM sampling test
4. docs: update AGENTS.md with sampling details

Notizen:

• Erste 50 Spalten genommen (alphabetisch)
• TODO: Smarter Algorithmus (Varianz-basiert)

```

Phase 3: CHECK

• Ergebnisse messen vs. Erfolgskriterien
• Unerwartete Nebenwirkungen dokumentieren
• Lessons Learned sammeln

```markdown

Messungen:

| Metrik | Ziel | Ist | Status |

|--------|------|-----|--------|

| P95 Latency | < 10s | 8.2s | OK |

| SECOM Timeout | 0 | 0 | OK |

| Analyse-Qualitaet | Keine Regression | Minor | WARNUNG |

Beobachtungen:

• Qualitaet leicht gesunken (fehlende Korrelationen)
• Erste 50 Spalten nicht optimal (viele NaN-Spalten)

Lessons Learned:

• Alphabetische Auswahl ist suboptimal
• Varianz-basierte Auswahl wuerde bessere Spalten finden

```

Phase 4: ACT

• Entscheiden: Standardisieren oder Iterieren?
• Prozess anpassen basierend auf Learnings
• Naechsten PDCA-Zyklus planen

```markdown

Entscheidung: ITERIEREN (nicht standardisieren)

Verbesserungen fuer naechsten Zyklus:

1. Varianz-basierte Spaltenauswahl implementieren
2. Nutzer-Feedback zu Analyse-Qualitaet einholen
3. A/B-Test: 50 vs 75 Spalten

Naechster PDCA-Zyklus:

• Start: 2025-01-16
• Fokus: Smart Column Selection Algorithm

```

---

Wann welchen Befehl nutzen?

| Situation | Befehl | Begruendung |

|-----------|--------|-------------|

| Production Bug | /why | Schnelle Root Cause Analyse |

| Komplexer Bug mit vielen Faktoren | /cause-and-effect | Strukturierte Ursachensammlung |

| Neues Feature planen | /plan-do-check-act | Iterative Implementierung |

| Refactoring | /plan-do-check-act | Messbare Verbesserung |

| Wiederkehrender Fehler | /why dann /cause-and-effect | Kombinierte Analyse |

Automatische Trigger

Dieser Skill aktiviert sich automatisch bei:

• git log mit Muster "fix:" oder "hotfix:"
• Vercel Deployment Failures
• Test-Failures in CI/CD
• Keywords: "bug", "fehler", "timeout", "crash", "regression"

Quality Gate Integration

Nach jedem PDCA-Zyklus:

```bash

npx tsc --noEmit # TypeScript Check

npm run build # Build

npm run test # Unit Tests

npm run test:e2e # E2E (optional)

```

---

• [ ] Continuous Improvement: Ist die Aenderung inkrementell? (Max 1 Feature pro Commit)
• [ ] Poka-Yoke: Sind Fehler durch Typen verhindert? (Keine Runtime-Validierung wo Compile-Time moeglich)
• [ ] Standardized Work: Folgt der Code etablierten Patterns? (API Response Format, Error Handling)
• [ ] Just-In-Time: Wird nur das implementiert was JETZT gebraucht wird? (Kein "fuer spaeter")

Nach jeder Analyse:

1. Ergebnis in docs/kaizen/ ablegen
2. Commit Message mit Kaizen-Referenz: fix: resolve timeout (5-Whys #12)
3. Lessons Learned in CHANGELOG.md

---

• [Toyota Production System](https://www.toyota-global.com/company/vision_philosophy/toyota_production_system/)
• [Lean Manufacturing Principles](https://www.lean.org/explore-lean/what-is-lean/)
• [The Toyota Way - Jeffrey Liker](https://www.mheducation.com/highered/product/toyota-way-liker/M9780071392310.html)

---

Entwickelt fuer fabrikIQ - Manufacturing Intelligence Platform

DSGVO-konform | Region fra1 | Dresden AI Insights