← Back to Phase Detail

Routing Logic

The complete Phase 0 decision tree: source detection, HARD BLOCK, audience routing, and every edge case with full pseudocode

On this page

01Source Detection in Detail 02The HARD BLOCK Mechanism 03Audience Routing 04Edge Cases & Error Handling

01

Source Detection in Detail

Source detection is the very first decision node in the orchestrator. Before any analysis token is spent, the skill must know where the source code lives. There are exactly three paths — and every edge case that can occur along the way.

The complete decision tree:

💬

User Input

→

🔍

Pattern Match

→

✅

Validation

→

📂

Source Object

// ============================================
// SOURCE DETECTION — Complete Algorithm
// ============================================

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

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

        // Edge case: GitHub URL without .git suffix
        if is_github_url(input) and !ends_with(input, ".git"):
            input = input + ".git"

        // Edge case: URL contains /tree/branch or /blob/...
        if contains(input, "/tree/") or contains(input, "/blob/"):
            input = extract_repo_root(input)

        // Clone to temporary directory
        temp = create_temp_dir()
        result = git_clone(input, temp)

        if result.error:
            if result.code == 128:  // Auth error
                raise "Repository unreachable. Private? Token missing."
            if result.code == 404:
                raise "Repository does not exist: " + input
            raise "git clone failed: " + result.stderr

        return {
            type: "git",
            path: temp,
            url: input,
            cleanup: true  // delete temp dir after completion
        }

    // ---- PATH 2: Filesystem Path ----
    if looks_like_path(input):
        resolved = resolve_path(input)

        // Edge case: path exists but is a FILE
        if is_file(resolved):
            raise "Path points to a file, not a directory: "
                 + resolved
                 + "\nPlease provide the parent directory."

        if !exists(resolved):
            raise "Directory does not exist: " + resolved

        if count_readable_files(resolved) == 0:
            raise "Directory contains no readable files: " + resolved

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

    // ---- PATH 3: CWD (current working directory) ----
    if input == "." or input == "./" or input == "":
        cwd = get_working_directory()
        return validate_and_return_cwd(cwd)

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

    // ---- NO MATCH ----
    raise "Source not recognized. Please provide:\n"
         + "  - GitHub/GitLab URL\n"
         + "  - Local path (absolute or relative)\n"
         + "  - '.' for the current directory"

function validate_and_return_cwd(cwd):
    if count_readable_files(cwd) == 0:
        raise "CWD contains no analyzable files: " + cwd
    return { type: "cwd", path: cwd, url: null, cleanup: false }
            

Path 1 — Git URL: If the input starts with "http" or "git@", a git clone is executed into a temporary directory. GitHub URLs without a ".git" suffix get it appended automatically. URLs containing "/tree/" or "/blob/" (pointing to a subdirectory or file in the browser) are reduced to the repository root. If the clone fails, the skill distinguishes between auth errors (private repo, missing token) and 404 (repo does not exist).

Path 2 — Filesystem Path: Absolute paths (/...), relative paths (./...), and home paths (~/) are resolved. Critical edge case: if the path points to a file instead of a directory, the skill does not fail silently but provides a clear error message suggesting the parent directory. Empty directories also trigger an error.

Path 3 — CWD: The input ".", empty input, or phrases like "this project" use the current working directory. Here too, the directory must contain at least one readable file.

No Match: If none of the three patterns matches, an error message listing all three accepted formats is shown. No fallback, no guessing.

02

The HARD BLOCK Mechanism

After successful source detection, the orchestrator faces an impassable gate: two mandatory questions must be answered before Phase 1 may begin. There is no shortcut, no default, and no "later".

HARD BLOCK — The Two Mandatory Questions

Question 1: Language(s)?

Accepted: "de", "en", "both", "Deutsch", "English", "German and English". Determines filename suffixes (_de.html, _en.html) and content language.

Question 2: Audiences?

Accepted: explicit naming of one or more standard audiences (Developers, Users, Executives) or custom audiences. "all" and "everyone" are not accepted — too vague.

// ============================================
// HARD BLOCK — Mandatory Question Guard
// ============================================

const MANDATORY_QUESTIONS = [
    {
        id: "languages",
        prompt: "What language(s) should the course use? (de, en, or both)",
        validator: validate_languages
    },
    {
        id: "audiences",
        prompt: "Which audiences? (e.g. Developers, Users, Executives)",
        validator: validate_audiences
    }
]

function hard_block(source):
    answers = {}
    for q in MANDATORY_QUESTIONS:
        attempt = 0
        while !answers[q.id]:
            attempt += 1
            if attempt > 5:
                raise "Mandatory question " + q.id
                     + " unanswered after 5 attempts. Aborting."

            response = ask_user(q.prompt)

            // Detect and reject bypass attempts
            if is_bypass_attempt(response):
                // "just go", "skip", "start", "whatever", "default"
                notify("This question cannot be skipped. "
                     + "Please answer specifically.")
                continue

            parsed = q.validator(response)
            if parsed.valid:
                answers[q.id] = parsed.value
            else:
                notify(parsed.error_message)

    return answers

function validate_audiences(response):
    if matches(response, /^(all|everyone|every\s*one|f.r\s*jed)/i):
        return {
            valid: false,
            error_message: "'Everyone' is too unspecific. "
              + "Please name audiences: Developers, Users, "
              + "Executives, or custom names."
        }
    found = []
    if mentions(response, "developer|entwickler|dev"):
        found.push(AUDIENCE_DEV)
    if mentions(response, "user|anwender|nutzer"):
        found.push(AUDIENCE_USER)
    if mentions(response, "executive|entscheider|manager"):
        found.push(AUDIENCE_EXEC)
    custom = extract_custom_audiences(response)
    found = found.concat(custom)
    if found.length == 0:
        return { valid: false, error_message: "No recognizable audience found." }
    return { valid: true, value: found }
            

The guard logic works as follows:

1. The orchestrator has a fixed list of two mandatory questions. Each question has a prompt and a validator.

2. For each question, the user is asked. Their response is first checked for bypass attempts: "just go", "skip", "whatever", and similar phrases are detected and rejected.

3. Then the response is validated. For audiences: "all" or "everyone" is too vague and rejected. Specific names (Developers, Users, Executives) or custom audiences are accepted.

4. The loop repeats up to 5 times. After that, the skill execution is aborted — better no result than a wrong one.

Core rule: No defaults. No inference from context. No heuristics. The user must answer explicitly.

03

Audience Routing

Once the mandatory questions are answered, the orchestrator must derive a pipeline configuration from the responses: who gets which files, with which suffixes, to what depth?

Order	Audience	File Suffix	Example L0
1st (Most general)	Most general audience	No suffix	`index_en.html`
2nd	Developers	`_dev`	`index_dev_en.html`
3rd	Executives	`_exec`	`index_exec_en.html`
4th (Custom)	e.g. "DevOps Team"	`_devops-team`	`index_devops-team_en.html`

// ============================================
// AUDIENCE ROUTING — Pipeline Configuration
// ============================================

const AUDIENCE_PROFILES = {
    "users":      { emoji: "👤", suffix: "",      max_level: 2,
                     thresholds: { L1: 7, L2: 9 } },
    "developers": { emoji: "🔧", suffix: "_dev",  max_level: 3,
                     thresholds: { L1: 6, L2: 8, L3: 8 } },
    "executives": { emoji: "📊", suffix: "_exec", max_level: 1,
                     thresholds: { L1: 8 } }
}

function build_routing_table(audiences, languages):
    pipelines = []
    sorted = sort_by_generality(audiences)
    sorted[0].suffix_override = ""  // first = no suffix

    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.thresholds,
                naming: "[slug]" + suffix + "_" + lang + ".html"
            })
    return pipelines
            

The routing algorithm creates one pipeline per audience-language combination:

1. Audiences are sorted by generality. The most general (typically Users) comes first and receives no suffix — their files are the "default" view.

2. Each subsequent audience gets its predefined suffix: _dev for Developers, _exec for Executives, a derived slug for custom audiences.

3. For each audience, as many pipelines as languages are created. With 2 audiences and 2 languages, this yields 4 pipelines.

4. Each pipeline contains all information the pipeline agent needs: audience name, emoji, suffix, language, max depth, HS thresholds, and naming pattern.

04

Edge Cases & Error Handling

Every decision node in Phase 0 has failure states. Here is the complete directory of all edge cases with their handling strategies.

Edge Case	Detection	Handling
User changes audiences mid-generation	"Change audiences" during Phase 3/4	Full restart. Discard all generated files. Rerun Phase 0 with new answers. Partial updates are inconsistent.
Source directory is empty	`count_readable_files() == 0`	Immediate error in source detection. Clear message: "No analyzable files found."
Path does not exist	`!exists(resolved_path)`	Immediate error. Show path so user can spot the typo.
Path points to a file	`is_file(resolved_path)`	Error with hint: "Please provide the parent directory." The skill analyzes projects, not individual files.
GitHub returns 404	`git clone exit code 128`	Distinguish: repo does not exist vs. repo is private. Both produce code 128, but stderr differs.
Private repo, no token	`stderr contains "auth"`	Error with clear hint about missing token. Suggest cloning locally as alternative.
User says "all" as audience	`validate_audiences()` rejects	Re-prompt: "Please name audiences specifically." No default to all three standard audiences.
User fails to answer 5 times	`attempt > max_attempts`	Skill abort. Better no result than a wrong one.

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

function handle_audience_change(new_audiences, state):
    if state.phase >= 1:
        // Already-generated files are inconsistent.
        // Reason: HS scores were computed for old audiences.
        // Curricula don't match. Cross-links point to
        // non-existent audience variants.
        notify("Audience change requires full restart.")
        delete_generated_files(state.output_dir)
        state.phase = 0
        state.answers.audiences = new_audiences
        return restart_from_phase_0(state)
    else:
        state.answers.audiences = new_audiences
        return continue_phase_0(state)

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

function diagnose_clone_failure(stderr, url):
    if contains(stderr, "not found"):
        return { type: "not_found",
                 message: "Repository does not exist: " + url }
    if contains(stderr, "Authentication"):
        return { type: "auth_required",
                 message: "Repository is private. "
                        + "Provide a token or clone locally." }
    return { type: "unknown",
             message: "git clone failed:\n" + stderr }
            

Audience change mid-generation: If the user wants to change audiences while generation is running, there is no way to "bend" already-generated files. Helpfulness scores are audience-specific, curricula are based on those scores, and cross-links reference audience-specific variants. A partial update would lead to inconsistent results. Therefore: full restart.

GitHub error diagnosis: A failed clone (exit code 128) can have two causes: the repository does not exist, or it is private and access is missing. The skill analyzes the stderr output to distinguish between the two cases and provides a specific error message.

✏️ Knowledge Check

User says: "Make a course from ./my-project for everyone." Is the HARD BLOCK satisfied?

Yes — source is clear (./my-project) and "everyone" means all three standard audiences

No — "everyone" is too vague, specific audiences are missing, and language is not specified

Partially — source is fine, but audiences and language still need follow-up

🔧 Developer — All L3 Pages

01 Routing Logic 02 Thresholds 03 Pipeline Agent Prompts