← Zurück zum Phasen-Detail

Weichenstellung-Logik

Der vollständige Entscheidungsbaum von Phase 0: Source-Detection, HARD BLOCK, Zielgruppen-Routing und sämtliche Edge Cases mit komplettem Pseudocode

Auf dieser Seite

01Source-Detection im Detail 02Der HARD BLOCK Mechanismus 03Zielgruppen-Routing 04Edge Cases & Fehlerfälle

01

Source-Detection im Detail

Die Source-Detection ist der allererste Entscheidungsknoten im Orchestrator. Bevor irgendein Analyse-Token ausgegeben wird, muss der Skill wissen, wo der Quellcode liegt. Es gibt genau drei Pfade — und jeden Edge Case, der dabei auftreten kann.

Der vollständige Entscheidungsbaum:

💬

User-Eingabe

→

🔍

Pattern-Match

→

✅

Validierung

→

📂

Source-Objekt

// ============================================
// SOURCE DETECTION — Vollständiger Algorithmus
// ============================================

function detect_source(user_input):
    input = trim(user_input)

    // ---- PFAD 1: Git-URL ----
    // Erkennt: https://github.com/..., http://github.com/...
    // Erkennt: git@github.com:user/repo.git
    // Erkennt: https://gitlab.com/..., https://bitbucket.org/...
    if starts_with(input, "http") or starts_with(input, "git@"):

        // Edge Case: GitHub-URL ohne .git Suffix
        if is_github_url(input) and !ends_with(input, ".git"):
            input = input + ".git"
            // "https://github.com/user/repo" wird zu
            // "https://github.com/user/repo.git"

        // Edge Case: URL enthält /tree/branch oder /blob/...
        if contains(input, "/tree/") or contains(input, "/blob/"):
            input = extract_repo_root(input)
            // "https://github.com/user/repo/tree/main/src"
            // wird zu "https://github.com/user/repo.git"

        // Clone in temporäres Verzeichnis
        temp = create_temp_dir()
        result = git_clone(input, temp)

        if result.error:
            if result.code == 128:  // Auth-Fehler
                raise "Repository nicht erreichbar. Privat? Token fehlt."
            if result.code == 404:
                raise "Repository existiert nicht: " + input
            raise "git clone fehlgeschlagen: " + result.stderr

        return {
            type: "git",
            path: temp,
            url: input,
            cleanup: true  // temp-dir nach Abschluss löschen
        }

    // ---- PFAD 2: Dateisystem-Pfad ----
    // Erkennt: /absolute/path, ./relative/path, ~/home/path
    // Erkennt: C:\Windows\Path (Windows)
    if looks_like_path(input):
        resolved = resolve_path(input)

        // Edge Case: Pfad existiert, ist aber eine DATEI
        if is_file(resolved):
            raise "Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis: "
                 + resolved
                 + "\nBitte das übergeordnete Verzeichnis angeben."

        if !exists(resolved):
            raise "Verzeichnis existiert nicht: " + resolved

        if !is_directory(resolved):
            raise "Pfad ist kein Verzeichnis: " + resolved

        if count_readable_files(resolved) == 0:
            raise "Verzeichnis enthält keine lesbaren Dateien: " + resolved

        return {
            type: "local",
            path: resolved,
            url: null,
            cleanup: false
        }

    // ---- PFAD 3: CWD (aktuelles Verzeichnis) ----
    // Erkennt: ".", "./", "dieses Projekt", "this project"
    // Erkennt: "aktuelles Verzeichnis", "current dir"
    // Erkennt: Leere Eingabe (kein Pfad angegeben)
    if input == "." or input == "./" or input == "":
        cwd = get_working_directory()
        return validate_and_return_cwd(cwd)

    if matches(input, /dieses?\s*projekt|this\s*project|aktuell/i):
        cwd = get_working_directory()
        return validate_and_return_cwd(cwd)

    // ---- KEIN MATCH ----
    raise "Quelle nicht erkannt. Bitte angeben:\n"
         + "  - GitHub/GitLab URL\n"
         + "  - Lokaler Pfad (absolut oder relativ)\n"
         + "  - '.' für das aktuelle Verzeichnis"

function validate_and_return_cwd(cwd):
    if count_readable_files(cwd) == 0:
        raise "CWD enthält keine analysierbaren Dateien: " + cwd
    return {
        type: "cwd",
        path: cwd,
        url: null,
        cleanup: false
    }

// Hilfsfunktionen
function looks_like_path(s):
    return starts_with(s, "/")
        or starts_with(s, "./")
        or starts_with(s, "../")
        or starts_with(s, "~/")
        or matches(s, /^[A-Z]:\\/)  // Windows
            

Pfad 1 — Git-URL: Wenn die Eingabe mit „http“ oder „git@“ beginnt, wird ein Git-Clone in ein temporäres Verzeichnis ausgeführt. GitHub-URLs ohne „.git“-Suffix bekommen diesen automatisch angehängt. URLs mit „/tree/“ oder „/blob/“ (die auf ein Unterverzeichnis oder eine Datei im Browser zeigen) werden auf die Repo-Root zurückgeführt. Schlägt der Clone fehl, wird zwischen Auth-Fehler (privates Repo, Token fehlt) und 404 (Repo existiert nicht) unterschieden.

Pfad 2 — Dateisystem-Pfad: Absolute Pfade (/...), relative Pfade (./...) und Home-Pfade (~/) werden aufgelöst. Kritischer Edge Case: Wenn der Pfad auf eine Datei statt ein Verzeichnis zeigt, wird nicht still fehlgeschlagen, sondern eine klare Fehlermeldung ausgegeben, die das übergeordnete Verzeichnis vorschlägt. Leere Verzeichnisse erzeugen ebenfalls einen Fehler.

Pfad 3 — CWD: Die Eingabe „.“, eine leere Eingabe, oder Formulierungen wie „dieses Projekt“ nutzen das aktuelle Arbeitsverzeichnis. Auch hier muss das Verzeichnis mindestens eine lesbare Datei enthalten.

Kein Match: Wenn keines der drei Muster zutrifft, wird eine Fehlermeldung mit allen drei akzeptierten Formaten angezeigt. Es gibt keinen Fallback und kein Raten.

02

Der HARD BLOCK Mechanismus

Nach erfolgreicher Source-Detection steht der Orchestrator vor einem unumgehbaren Gate: Zwei Pflichtfragen müssen beantwortet werden, bevor Phase 1 starten darf. Es gibt keine Abkürzung, keinen Default und kein „Später“.

HARD BLOCK — Die zwei Pflichtfragen

Frage 1: Sprache(n)?

Akzeptierte Antworten: „de“, „en“, „beide“/„both“, „Deutsch“, „English“, „Deutsch und Englisch“. Bestimmt die Dateinamens-Suffixe (_de.html, _en.html) und die Inhaltssprache.

Frage 2: Zielgruppen?

Akzeptierte Antworten: Explizite Nennung von einer oder mehreren der drei Standard-Audiences (Entwickler, Anwender, Entscheider) oder benutzerdefinierte Audiences. „alle“ und „für jeden“ sind nicht akzeptiert — zu vage.

Warum kein „einfach loslegen“?

Wenn der Skill raten würde („vermutlich Deutsch, vermutlich Entwickler“), könnte er einen kompletten Kurs mit 50+ Dateien generieren — nur um festzustellen, dass der User eigentlich Englisch für Entscheider wollte. Die zwei Fragen kosten 10 Sekunden. Eine falsche Annahme kostet Minuten an verschwendeter Generierung. Das Kosten-Nutzen-Verhältnis ist eindeutig.

Guard-Logic — Vollständiger Pseudocode:

// ============================================
// HARD BLOCK — Pflichtfragen-Guard
// ============================================

const MANDATORY_QUESTIONS = [
    {
        id: "languages",
        prompt_de: "In welcher Sprache soll der Kurs erstellt werden?
                    (de, en, oder beide)",
        prompt_en: "What language(s) should the course use?
                    (de, en, or both)",
        validator: validate_languages,
        // Akzeptiert: "de", "en", "beide", "both",
        //   "Deutsch", "English", "Deutsch und Englisch"
        // Ablehnt: "", "egal", "whatever", "standard"
    },
    {
        id: "audiences",
        prompt_de: "Für welche Zielgruppen? (z.B. Entwickler,
                    Anwender, Entscheider — oder eigene)",
        prompt_en: "Which audiences? (e.g. Developers, Users,
                    Executives — or custom)",
        validator: validate_audiences,
        // Akzeptiert: "Entwickler", "Entwickler und Anwender",
        //   "Developers, Users", "DevOps Team (custom)"
        // Ablehnt: "alle", "für jeden", "everyone",
        //   "all", "no preference"
    }
]

function hard_block(source):
    answers = {}

    for q in MANDATORY_QUESTIONS:
        max_attempts = 5  // Endlos-Schleifen verhindern
        attempt = 0

        while !answers[q.id]:
            attempt += 1

            if attempt > max_attempts:
                raise "Pflichtfrage " + q.id
                     + " nach 5 Versuchen unbeantwortet."
                     + " Skill-Ausführung abgebrochen."

            response = ask_user(q.prompt_de)

            // Bypass-Versuche erkennen und ablehnen
            if is_bypass_attempt(response):
                // "leg los", "just go", "skip", "start",
                // "mach einfach", "just do it", "egal"
                notify("Diese Frage kann nicht übersprungen "
                     + "werden. Bitte konkret antworten.")
                continue

            // Validierung
            parsed = q.validator(response)

            if parsed.valid:
                answers[q.id] = parsed.value
            else:
                notify(parsed.error_message)
                // z.B. "'für alle' ist zu vage.
                //  Bitte nenne spezifische Zielgruppen."

    return answers

function is_bypass_attempt(response):
    bypass_patterns = [
        /^(leg\s*los|start|skip|go|mach|just)/i,
        /^(egal|whatever|no\s*preference)/i,
        /^(standard|default|auto)/i
    ]
    return bypass_patterns.some(p => matches(response, p))

function validate_audiences(response):
    // "alle", "everyone", "für jeden" = ABGELEHNT
    if matches(response, /^(alle|all|everyone|für\s*jed)/i):
        return {
            valid: false,
            error_message:
                "'Für alle' ist zu unspezifisch. Bitte nenne "
              + "die Zielgruppen konkret: Entwickler, Anwender, "
              + "Entscheider — oder eigene Namen."
        }

    // Bekannte Audiences matchen
    found = []
    if mentions(response, "entwickler|developer|dev"):
        found.push(AUDIENCE_DEV)
    if mentions(response, "anwender|user|nutzer"):
        found.push(AUDIENCE_USER)
    if mentions(response, "entscheider|executive|manager"):
        found.push(AUDIENCE_EXEC)

    // Custom-Audiences erkennen
    custom = extract_custom_audiences(response)
    found = found.concat(custom)

    if found.length == 0:
        return {
            valid: false,
            error_message:
                "Keine erkennbare Zielgruppe gefunden. "
              + "Bekannt: Entwickler, Anwender, Entscheider. "
              + "Oder eigene angeben."
        }

    return { valid: true, value: found }
            

Die Guard-Logik arbeitet so:

1. Der Orchestrator hat eine feste Liste von zwei Pflichtfragen. Jede Frage hat einen Prompt (DE + EN) und einen Validator.

2. Für jede Frage wird der User gefragt. Seine Antwort wird zuerst auf Bypass-Versuche geprüft: „leg los“, „just go“, „skip“, „egal“ und ähnliche werden erkannt und abgelehnt. Die Nachricht erklärt, warum die Frage nicht übersprungen werden kann.

3. Dann wird die Antwort validiert. Für Zielgruppen bedeutet das: „alle“ oder „für jeden“ ist zu vage und wird abgelehnt. Spezifische Namen (Entwickler, Anwender, Entscheider) oder Custom-Audiences werden akzeptiert.

4. Die Schleife wiederholt sich maximal 5-mal. Danach wird die Skill-Ausführung abgebrochen — lieber kein Ergebnis als ein falsches.

Kernregel: Es gibt keine Defaults. Keine Inferenz aus dem Kontext. Keine Heuristik. Der User muss explizit antworten.

03

Zielgruppen-Routing

Sobald die Pflichtfragen beantwortet sind, muss der Orchestrator aus den Antworten eine Pipeline-Konfiguration ableiten: Wer bekommt welche Dateien, mit welchen Suffixen, bis zu welcher Tiefe?

Suffix-Bestimmung — Reihenfolge entscheidet:

Reihenfolge	Audience	Datei-Suffix	Beispiel L0
1. (Erste/Allgemeinste)	Allgemeinste Audience	Kein Suffix	`index_de.html`
2.	Entwickler	`_dev`	`index_dev_de.html`
3.	Entscheider	`_exec`	`index_exec_de.html`
4. (Custom)	z.B. „DevOps Team“	`_devops-team`	`index_devops-team_de.html`

Regel: Die allgemeinste Audience (typischerweise Anwender) bekommt keinen Suffix und wird damit zur Standard-Ansicht. Alle weiteren Audiences bekommen ein Suffix. Diese Reihenfolge ist: Anwender (kein Suffix) → Entwickler (_dev) → Entscheider (_exec) → Custom (_slug).

Routing-Tabelle — Ableitung:

// ============================================
// ZIELGRUPPEN-ROUTING — Pipeline-Konfiguration
// ============================================

const AUDIENCE_PROFILES = {
    "anwender": {
        emoji: "👤", suffix: "",     max_level: 2,
        hs_thresholds: { L1: 7, L2: 9 }
    },
    "entwickler": {
        emoji: "🔧", suffix: "_dev", max_level: 3,
        hs_thresholds: { L1: 6, L2: 8, L3: 8 }
    },
    "entscheider": {
        emoji: "📊", suffix: "_exec", max_level: 1,
        hs_thresholds: { L1: 8 }
    }
}

function build_routing_table(audiences, languages):
    pipelines = []

    // Reihenfolge bestimmen: allgemeinste zuerst
    sorted = sort_by_generality(audiences)
    // Reihenfolge: Anwender > Entwickler > Entscheider > Custom

    // Erste Audience bekommt keinen Suffix
    sorted[0].suffix_override = ""

    for audience in sorted:
        profile = get_profile(audience)

        for lang in languages:
            pipelines.push({
                audience: audience.name,
                emoji: profile.emoji,
                suffix: audience.suffix_override ?? profile.suffix,
                language: lang,
                max_level: profile.max_level,
                thresholds: profile.hs_thresholds,
                output_dir: "./output/",
                // Dateiname-Pattern:
                // [slug][suffix]_[lang].html
                naming: build_naming_pattern(
                    audience.suffix_override ?? profile.suffix,
                    lang
                )
            })

    return pipelines

// Beispiel-Ausgabe für audiences=["Anwender","Entwickler"], langs=["de","en"]:
// [
//   { audience: "Anwender", suffix: "", lang: "de",
//     naming: "[slug]_de.html", max_level: 2 },
//   { audience: "Anwender", suffix: "", lang: "en",
//     naming: "[slug]_en.html", max_level: 2 },
//   { audience: "Entwickler", suffix: "_dev", lang: "de",
//     naming: "[slug]_dev_de.html", max_level: 3 },
//   { audience: "Entwickler", suffix: "_dev", lang: "en",
//     naming: "[slug]_dev_en.html", max_level: 3 },
// ]
            

Der Routing-Algorithmus erstellt eine Pipeline pro Audience-Sprach-Kombination:

1. Audiences werden nach Allgemeinheit sortiert. Die allgemeinste (typischerweise Anwender) kommt zuerst und bekommt keinen Suffix — ihre Dateien sind die „Standard“-Ansicht.

2. Jede weitere Audience bekommt ihren vordefinierten Suffix: _dev für Entwickler, _exec für Entscheider, ein abgeleiteter Slug für Custom-Audiences.

3. Für jede Audience werden so viele Pipelines wie Sprachen erstellt. Bei 2 Audiences und 2 Sprachen ergeben sich 4 Pipelines.

4. Jede Pipeline enthält: Audience-Name, Emoji, Suffix, Sprache, maximale Tiefe, HS-Schwellenwerte, Ausgabeverzeichnis und Dateinamens-Pattern. Damit hat der Pipeline-Agent alle Informationen, die er braucht.

04

Edge Cases & Fehlerfälle

Jeder Entscheidungsknoten in Phase 0 hat Fehlerzustände. Hier ist das vollständige Verzeichnis aller Edge Cases mit der jeweiligen Behandlungsstrategie.

Edge Case	Erkennung	Behandlung
User ändert Audiences mid-generation	„Ändere Zielgruppen“ während Phase 3/4 läuft	Voller Neustart. Alle bereits generierten Dateien verwerfen. Phase 0 mit neuen Antworten komplett neu durchlaufen. Teilgenerierung ist inkonsistent.
Quellverzeichnis ist leer	`count_readable_files() == 0`	Sofortiger Fehler in Source-Detection. Klare Meldung: „Keine analysierbaren Dateien gefunden.“ Keine Analyse starten.
Pfad existiert nicht	`!exists(resolved_path)`	Sofortiger Fehler. Pfad ausgeben, damit der User den Tippfehler erkennen kann.
Pfad zeigt auf eine Datei	`is_file(resolved_path)`	Fehler mit Hinweis: „Bitte das übergeordnete Verzeichnis angeben.“ Der Skill analysiert Projekte, nicht einzelne Dateien.
GitHub gibt 404 zurück	`git clone exit code 128 + „not found“`	Unterscheidung: Repository existiert nicht vs. Repository ist privat. Beide Fälle produzieren 128, aber die stderr-Meldung unterscheidet sich.
Privates Repo, kein Token	`git clone exit code 128 + „auth“`	Fehler mit klarem Hinweis auf fehlendes Token. Kein stiller Abbruch.
Monorepo ohne klaren Entry-Point	Kein README, kein offensichtlicher Entry-Point in Root	Phase 1 scant Unterverzeichnisse und behandelt jedes Paket als eigenständigen Teilbaum. Nicht Fehler, aber Warnung an User.
User gibt „alle“ als Audience an	`validate_audiences()` rejektiert vage Antworten	Re-Prompt: „Bitte nenne die Zielgruppen konkret.“ Kein Default auf alle drei Standard-Audiences.
Netzwerkfehler während Clone	`git clone timeout / DNS failure`	Fehler mit Netzwerk-Hinweis. Vorschlag: Lokalen Pfad als Alternative verwenden, falls Repo bereits geklont ist.
User antwortet 5x nicht korrekt	HARD BLOCK `attempt > max_attempts`	Skill-Abbruch. Besser kein Ergebnis als ein falsches. Fehlermeldung erklärt warum.

// ============================================
// EDGE CASE: Mid-Generation Audience-Wechsel
// ============================================

function handle_audience_change(new_audiences, state):
    // state.phase gibt die aktuelle Phase an
    if state.phase >= 1:
        // Bereits generierte Dateien sind inkonsistent.
        // Grund: Helpfulness-Scores wurden für die
        // alten Audiences berechnet. Curricula passen nicht.
        // Cross-Links zeigen auf nicht-existente Varianten.

        notify("Zielgruppen-Änderung erfordert vollständigen Neustart.")
        notify("Bereits generierte Dateien werden verworfen.")

        // Cleanup
        delete_generated_files(state.output_dir)

        // Phase 0 komplett neu starten
        state.phase = 0
        state.answers.audiences = new_audiences
        // Sprache bleibt erhalten (keine Änderung)

        return restart_from_phase_0(state)

    else:
        // Noch in Phase 0: einfach überschreiben
        state.answers.audiences = new_audiences
        return continue_phase_0(state)

// ============================================
// EDGE CASE: GitHub 404 vs. Privat
// ============================================

function diagnose_clone_failure(stderr, url):
    if contains(stderr, "not found"):
        return {
            type: "not_found",
            message: "Repository existiert nicht: " + url
                   + "\nBitte URL prüfen."
        }
    if contains(stderr, "Authentication") or
       contains(stderr, "could not read"):
        return {
            type: "auth_required",
            message: "Repository ist privat oder nicht erreichbar."
                   + "\nBitte GitHub-Token bereitstellen oder "
                   + "das Repo lokal klonen und den Pfad angeben."
        }
    return {
        type: "unknown",
        message: "git clone fehlgeschlagen:\n" + stderr
    }
            

Audience-Wechsel mid-generation: Wenn der User während der Generierung die Zielgruppen ändern will, gibt es keine Möglichkeit, die bereits generierten Dateien „umzubiegen“. Die Helpfulness-Scores sind audience-spezifisch, die Curricula basieren auf diesen Scores, und die Cross-Links verweisen auf audience-spezifische Varianten. Ein Teilupdate würde zu inkonsistenten Ergebnissen führen. Deshalb: voller Neustart.

GitHub-Fehler-Diagnose: Ein fehlgeschlagener Clone (Exit-Code 128) kann zwei Ursachen haben: Das Repository existiert nicht, oder es ist privat und der Zugriff fehlt. Der Skill analysiert die stderr-Ausgabe, um zwischen beiden Fällen zu unterscheiden, und gibt eine spezifische Fehlermeldung aus. Bei Auth-Fehlern wird als Alternative der lokale Pfad vorgeschlagen.

✏️ Wissenstest

User sagt: „Mach einen Kurs aus ./my-project für alle“. Ist der HARD BLOCK erfüllt?

Ja — Source ist klar (./my-project) und „für alle“ meint alle drei Standard-Audiences

Nein — „für alle“ ist zu vage, spezifische Zielgruppen fehlen, und Sprache ist nicht angegeben

Teilweise — Source ist erfüllt, aber Audiences und Sprache müssen noch nachgefragt werden

🔧 Entwickler — Alle L3-Seiten

01 Weichenstellung-Logik 02 Schwellenwerte 03 Pipeline-Agent-Prompts