← Zurück zum Orchestrator

Phasen-Steuerung im Detail

Bootstrap, Analyse, Curriculum-Ableitung und Polish-Algorithmus — die Kernphasen mit vollständigem Pseudocode, Edge Cases und Entscheidungslogik

Auf dieser Seite

01Phase 0 — Bootstrap-Logik 02Phase 1 — Analyse-Strategie 03Phase 2 — Curriculum per Zielgruppe 04Phase 5 — Polish-Algorithmus

01

Phase 0 — Bootstrap-Logik

Bevor der Orchestrator irgendeine Analyse startet, muss er wissen, wo der Quellcode liegt. Phase 0 erkennt die Quelle und stellt sicher, dass alle Pflichtfragen beantwortet sind, bevor ein einziger Token für Analyse ausgegeben wird.

Source-Detection — drei Pfade:

🌐

GitHub URL

→

📥

git clone

📂

Lokaler Pfad

→

📁

Direkt-Zugriff

💬

„dieses Projekt“

→

📍

CWD nutzen

HARD BLOCK — Pflichtfragen

Phase 0 stellt nach der Source-Detection einen Block von Pflichtfragen. Der Orchestrator darf nicht zu Phase 1 weitergehen, bevor alle beantwortet sind. Fehlende Antworten erzeugen keine Defaults — sie erzeugen eine erneute Nachfrage. Das verhindert, dass der Skill mit falschen Annahmen einen kompletten Kurs baut.

Sprache(n)? — de, en, oder beide (bestimmt Dateinamens-Suffixe und Inhalt)

Integrationsmodus? — standalone oder embedded (bestimmt Header/Footer)

Zielgruppen? — Welche der drei Audiences sollen bedient werden

// Phase 0: Source Detection
function detect_source(user_input):
    // Pattern 1: GitHub URL
    if matches(user_input, /^https?:\/\/github\.com\/[\w-]+\/[\w.-]+/):
        repo_url = extract_repo_url(user_input)
        if is_private(repo_url) and !has_token():
            // Edge case: private repos need auth
            raise "Repository ist privat. Bitte Token bereitstellen."
        local_path = git_clone(repo_url, temp_dir())
        return { type: "github", path: local_path, url: repo_url }

    // Pattern 2: Local path
    if is_absolute_path(user_input) or is_relative_path(user_input):
        resolved = resolve_path(user_input)
        if !exists(resolved):
            raise "Pfad existiert nicht: " + resolved
        if !has_readable_files(resolved):
            raise "Keine lesbaren Dateien gefunden in: " + resolved
        return { type: "local", path: resolved, url: null }

    // Pattern 3: "this project" / "dieses Projekt"
    if matches(user_input, /dieses?\s*projekt|this\s*project|aktuell/i):
        cwd = get_working_directory()
        if !has_readable_files(cwd):
            raise "CWD enthält keine analysierbaren Dateien."
        return { type: "cwd", path: cwd, url: null }

    // Fallback: kein erkanntes Pattern
    raise "Quelle nicht erkannt. Bitte GitHub-URL, Pfad oder 'dieses Projekt' angeben."

// HARD BLOCK: Pflichtfragen
function mandatory_questions(source):
    answers = {}
    for question in [LANGUAGE, INTEGRATION_MODE, AUDIENCES]:
        while !is_valid(answers[question]):
            answers[question] = ask_user(question)
            if !is_valid(answers[question]):
                notify("Bitte beantworte die Frage.")
                // KEIN Default. KEIN Skip. Schleife.
    return answers
            

Schritt 1: Der Orchestrator prüft die Nutzer-Eingabe auf drei Muster: GitHub-URL (beginnt mit https://github.com/...), lokaler Dateipfad (absolut oder relativ), oder eine Formulierung wie „dieses Projekt“.

Schritt 2: Je nach Muster wird geklont, der Pfad aufgelöst oder das aktuelle Verzeichnis verwendet. Bei Fehlern (privates Repo, nicht existierender Pfad, leeres Verzeichnis) bricht Phase 0 mit einer klaren Fehlermeldung ab.

Schritt 3: Danach kommen die Pflichtfragen. Die drei Fragen (Sprache, Integrationsmodus, Zielgruppen) werden in einer Schleife gestellt. Keine Frage darf übersprungen werden. Es gibt keine Standardwerte. Die Schleife wiederholt sich, bis eine gültige Antwort vorliegt.

Edge Case: Wenn ein Nutzer eine GitHub-URL angibt, die auf ein privates Repo zeigt, und kein Token verfügbar ist, scheitert der Clone. Die Fehlermeldung enthält einen Hinweis auf das fehlende Token — kein stiller Abbruch.

02

Phase 1 — Analyse-Strategie

Phase 1 liest den Quellcode und baut einen Themenbaum mit Komplexitätsbewertungen. Der Ansatz ist top-down: Zuerst README und Einstiegspunkte, dann immer tiefer in die Struktur.

Analyse-Reihenfolge:

1

README + Docs lesen

Gibt den Projekt-Kontext: Was macht das Projekt? Welche Technologien? Was ist der Zweck? Diese Information framt alle weiteren Entscheidungen.

2

Entry Points identifizieren

main.py, index.ts, App.vue, Dockerfile — die Dateien, die das System starten. Von hier aus wird die Abhängigkeitskette verfolgt.

3

Akteure und Datenflüsse kartieren

Wer oder was interagiert mit dem System? APIs, Benutzer, Datenbanken, externe Services. Jeder Akteur wird ein potenzielles Thema.

4

Patterns und Architektur-Muster erkennen

MVC, Event-Driven, Microservices, Monolith? Das Architektur-Pattern bestimmt, wie Themen gruppiert und verschachtelt werden.

5

Komplexität pro Thema bewerten

Jedes Thema bekommt eine initiale Komplexitätsschätzung (0–3). Diese bestimmt, ob das Thema ein Kandidat für tiefere Levels ist.

Themenbaum-Aufbau:

// Theme Tree Output (Phase 1)
theme_tree = {
  project: "MeinProjekt",
  detected_patterns: ["REST API", "React SPA", "PostgreSQL"],
  themes: [
    {
      id: "auth",
      name: "Authentifizierung & Autorisierung",
      complexity: 3,  // braucht eigene Seite mit Diagrammen
      sub_themes: ["OAuth2 Flow", "JWT Handling", "Role-Based Access"],
      l1_candidate: true,
      l2_candidate: true,
      l3_candidate: true,
      rationale: "Mehrere Flows, Edge Cases, Security-Aspekte"
    },
    {
      id: "api-design",
      name: "API-Design & Endpunkte",
      complexity: 2,  // mehrere Abschnitte nötig
      sub_themes: ["REST Conventions", "Error Responses", "Pagination"],
      l1_candidate: true,
      l2_candidate: true,
      l3_candidate: false,
      rationale: "Muster erklärbar, aber nicht so tief wie Auth"
    },
    {
      id: "setup",
      name: "Projekt einrichten",
      complexity: 1,  // ein Absatz reicht
      sub_themes: ["Installation", "Env-Variablen"],
      l1_candidate: true,
      l2_candidate: false,
      l3_candidate: false,
      rationale: "Einfache Anleitung, keine tiefe Erklärung nötig"
    },
    {
      id: "license",
      name: "Lizenz",
      complexity: 0,  // ein Satz
      sub_themes: [],
      l1_candidate: false,
      l2_candidate: false,
      l3_candidate: false,
      rationale: "Trivial, wird auf L0 erwähnt"
    }
  ]
}
            

Der Themenbaum ist das zentrale Artefakt von Phase 1. Jedes Thema bekommt:

• Komplexität 0: Trivial — in einem Satz auf dem L0-Überblick erwähnt. Kein eigenes Modul.
• Komplexität 1: Braucht einen Absatz. Kandidat für ein L1-Modul, aber nicht tiefer.
• Komplexität 2: Braucht mehrere Abschnitte. L1 + L2 Kandidat.
• Komplexität 3: Braucht eine eigene Seite mit Diagrammen, Code-Beispielen und Edge Cases. L1 + L2 + L3 Kandidat.

Das rationale-Feld dokumentiert, warum diese Komplexität gewählt wurde. Das ist entscheidend für Nachvollziehbarkeit — wenn später die Tiefenkarte zeigt, dass ein Thema keinen L3 bekommen hat, kann man zurück zur Begründung navigieren.

Edge Case: Monorepos

Bei Monorepos mit mehreren Paketen analysiert Phase 1 jedes Paket als eigenen Teilbaum. Die Themen werden dann auf oberster Ebene gruppiert (z.B. „Frontend“, „Backend“, „Shared“). Das verhindert, dass ein Monorepo einen flachen, unübersichtlichen Baum erzeugt.

03

Phase 2 — Curriculum per Zielgruppe

Phase 2 nimmt den Themenbaum aus Phase 1 und erstellt separate Curricula für jede Zielgruppe. Jede Audience bekommt nur die Themen und Tiefen, die für sie relevant sind.

Maximale Tiefe per Zielgruppe:

📊

Entscheider

max_level = L1. Kein L2, kein L3. Entscheider brauchen Überblick und Entscheidungsgrundlagen, keine Implementierungsdetails.

L0 + L1

👤

Anwender

max_level = L2. Bekommen L0, L1 und ausgewählte L2-Seiten. Kein L3 — zu technisch.

L0 + L1 + L2

🔧

Entwickler

max_level = L3. Voller Zugang. Bekommen alle Levels, inklusive Deep-Dives mit vollständigem Code.

L0 + L1 + L2 + L3

Curriculum-Ableitung — Algorithmus:

// Phase 2: Curriculum per Audience
function derive_curriculum(theme_tree, audience):
    max_level = get_max_level(audience)
    // Entscheider: 1, Anwender: 2, Entwickler: 3

    curriculum = { audience: audience, topics: [] }

    for theme in theme_tree.themes:
        // Berechne Helpfulness-Score für diese Audience
        hs = calculate_hs(theme, audience)

        // Bestimme geplante Levels
        planned_levels = []

        // L0 erwähnt: wenn HS >= 1
        if hs >= 1:
            planned_levels.push("L0_mention")

        // L1 eigenes Modul: wenn HS >= threshold_l1
        if hs >= THRESHOLD_L1[audience] and max_level >= 1:
            planned_levels.push("L1")

        // L2 eigene Seite: wenn HS >= threshold_l2
        if hs >= THRESHOLD_L2[audience] and max_level >= 2:
            planned_levels.push("L2")

        // L3 Deep-Dive: wenn HS >= threshold_l3
        if hs >= THRESHOLD_L3[audience] and max_level >= 3:
            planned_levels.push("L3")

        // ENTSCHEIDEND: Plane NICHT über max_level hinaus!
        // Entscheider bekommt NIEMALS L2/L3, egal wie hoch der HS.

        if planned_levels.length > 0:
            curriculum.topics.push({
                theme: theme,
                hs: hs,
                levels: planned_levels,
                stop_reason: determine_stop(hs, max_level, theme)
            })

    return curriculum

// Stop-Reasons (für Transparenz in der Tiefenkarte)
function determine_stop(hs, max_level, theme):
    if max_level reached:
        return "audience_max_level"  // z.B. Entscheider kann nicht tiefer als L1
    if hs < next_threshold:
        return "hs_below_threshold"  // Score zu niedrig für nächste Tiefe
    if theme.complexity < next_level:
        return "complexity_insufficient"  // Thema hat nicht genug Substanz
            

Der Algorithmus arbeitet so:

1. Für jede Zielgruppe gibt es eine maximale Tiefe. Entscheider: L1. Anwender: L2. Entwickler: L3. Darüber hinaus wird nie geplant.

2. Für jedes Thema wird der Helpfulness-Score (HS) berechnet — spezifisch für diese Zielgruppe. Dasselbe Thema hat unterschiedliche Scores je nach Audience.

3. Der HS wird gegen Schwellenwerte geprüft. Jedes Level hat einen Schwellenwert pro Audience. Nur wenn der Score den Schwellenwert erreicht und die maximale Tiefe es erlaubt, wird das Level eingeplant.

4. Jedes Thema bekommt einen Stop-Reason: Warum wurde nicht tiefer geplant? Drei mögliche Gründe: maximale Tiefe der Audience erreicht, Score unter Schwellenwert, oder das Thema hat einfach nicht genug Substanz für mehr.

Kern-Regel: Plane nie Seiten, die nicht gebaut werden. Wenn Entscheider maximal L1 bekommen, wird für sie kein L2 eingeplant — auch wenn der HS theoretisch hoch genug wäre.

Beispiel: Thema „Authentifizierung“ — drei Curricula

Zielgruppe	HS	Geplante Levels	Stop-Reason
📊 Entscheider	9	L0, L1	audience_max_level (max=L1)
👤 Anwender	7	L0, L1, L2	audience_max_level (max=L2)
🔧 Entwickler	10	L0, L1, L2, L3	complexity exhausted

04

Phase 5 — Polish-Algorithmus

Phase 5 ist der letzte Durchlauf. Hier wird nichts mehr inhaltlich geändert — nur verifiziert, repariert und konsistent gemacht. Der Polish-Algorithmus ist eine systematische Checkliste, die als interaktive Toggles implementiert ist.

Prüfungen im Detail:

✓ Cross-Level-Links verifizieren: Jeder Link von L1→L2 und L2→L3 muss auf eine existierende Datei zeigen. Verwaiste Links (Ziel wurde nicht generiert, weil HS zu niedrig) werden entfernt, nicht stehen gelassen.

✓ Audience-Switch auf L0 setzen: Der L0-Überblick muss Links zu allen generierten Audience-Varianten enthalten. Wenn nur Entwickler generiert wurden, erscheint kein Audience-Switch. Wenn alle drei da sind, werden alle drei verlinkt.

✓ Relative Pfade prüfen: L0→L1: l1/datei.html. L1→L2: ../l2/datei.html. L2→L3: ../l3/datei.html. Ein falscher Präfix bricht die Navigation.

✓ Breadcrumbs validieren: Jede Seite muss den korrekten Breadcrumb-Pfad haben. L2-Seiten: L0 › L1 › L2. L3-Seiten: L0 › L1 › L2 › L3. Die Breadcrumb-Links müssen auf die richtige Audience-Variante zeigen.

✓ Sprachversionen sicherstellen: Wenn beide Sprachen gewählt wurden, muss jede DE-Datei ein EN-Gegenstück haben und umgekehrt. Der Sprachschalter in der Nav muss auf die korrekte Gegendatei zeigen.

✓ Sibling-Navigation prüfen: Alle L2-Seiten der gleichen Audience müssen die gleiche Sibling-Nav am Ende haben. Die aktuelle Seite ist markiert, alle anderen sind verlinkt. Fehlende Geschwister werden aus der Nav entfernt.

✓ Level-Dots prüfen: Die Punkte im Hero müssen den aktuellen Level korrekt anzeigen. L2-Seite: zwei done, einer active, einer empty. Fehlerhafte Dots erzeugen falsche visuelle Hierarchie.

// Phase 5: Polish
function polish(generated_files):
    errors = []

    // 1. Cross-level links
    for file in generated_files:
        for link in extract_internal_links(file):
            target = resolve_relative(file.path, link.href)
            if !exists_in(generated_files, target):
                if link.is_deep_dive:
                    remove_link(file, link)  // L3 nicht generiert? Link entfernen
                    log("Removed dead deep-dive link: " + link.href)
                else:
                    errors.push({ file: file, link: link, type: "dead_link" })

    // 2. Audience switch auf L0
    l0_files = filter(generated_files, level == 0)
    for l0 in l0_files:
        audiences_present = get_audiences(generated_files)
        if audiences_present.length > 1:
            inject_audience_switch(l0, audiences_present)

    // 3. Relative paths
    for file in generated_files:
        expected_prefix = get_prefix(file.level, link.target_level)
        // L0→L1: "l1/", L1→L2: "../l2/", L2→L3: "../l3/"
        for link in extract_internal_links(file):
            if !link.href.startsWith(expected_prefix):
                fix_prefix(file, link, expected_prefix)
                log("Fixed path prefix: " + link.href)

    // 4. Breadcrumbs
    for file in generated_files:
        expected_crumbs = build_breadcrumb_chain(file)
        actual_crumbs = parse_breadcrumbs(file)
        if expected_crumbs != actual_crumbs:
            replace_breadcrumbs(file, expected_crumbs)

    // 5. Language pairs
    for file in generated_files:
        partner = get_language_partner(file)  // _de ↔ _en
        if partner and !exists_in(generated_files, partner):
            errors.push({ file: file, type: "missing_lang_partner" })

    return { fixed: count_fixes, errors: errors }
            

Der Polish-Algorithmus macht fünf Durchläufe:

1. Tote Links finden und behandeln: Jeder interne Link wird gegen die Liste generierter Dateien geprüft. Deep-Dive-Links zu nicht generierten L3-Seiten werden entfernt. Andere tote Links erzeugen einen Fehler.

2. Audience-Switch injizieren: Wenn mehrere Audiences generiert wurden, bekommt der L0-Überblick Links zu allen Varianten. Wenn nur eine Audience existiert, wird kein Switch angezeigt.

3. Pfad-Präfixe korrigieren: Links zwischen Levels müssen die richtige Verzeichnisstruktur widerspiegeln. Ein Link von einer L1-Seite zu einer L2-Seite muss mit ../l2/ beginnen, nicht mit l2/.

4. Breadcrumbs synchronisieren: Die Breadcrumb-Kette wird aus der Datei-Position im Levelbaum berechnet und mit dem tatsächlichen HTML verglichen.

5. Sprachpaare prüfen: Jede _de-Datei braucht ein _en-Gegenstück (wenn beide Sprachen gewählt wurden). Fehlende Partner werden als Fehler gemeldet.

✏️ Wissenstest

Phase 2 erstellt ein Curriculum für 📊 Entscheider. Soll es L2/L3-Kandidaten-Themen einplanen?

Nein — maximale Tiefe ist L1, es wird nichts geplant, was nicht gebaut wird

Ja — der HS könnte hoch genug sein, also sollte man planen

Nur L2, kein L3 — ein Level tiefer geht noch

🧪 Deep-Dive: Weichenstellung-Logik im Detail →

🔧 Entwickler — Alle L2-Seiten

01 Phasen-Detail 02 Score-Berechnung 03 Subagent-Architektur 04 Farbraum & Typografie 05 Hero & Modul-Patterns