How the Find-Your-Level Placement Quiz Maps Knowledge to a Starting Phase in AI-Engineering-From-Scratch

The find-your-level placement quiz converts three self-assessment answers into a numeric knowledge vector, aggregates scores against a 20-phase mapping table stored in skills/find-your-level/SKILL.md, and persists the highest-scoring phase to LEARNING.md as the learner’s deterministic entry point.

The AI-Engineering-From-Scratch curriculum uses a rule-based placement system to eliminate guesswork when entering the -phase learning path. The find-your-level placement quiz, implemented entirely within the repository’s skill runtime, evaluates learner confidence through targeted questions and maps responses to curriculum phases using a static JSON scoring matrix.

How the Placement Quiz Collects and Normalizes Input

The Three Assessment Questions

The quiz begins by prompting the learner with three targeted questions defined in skills/find-your-level/SKILL.md. These questions gauge comfort levels with core AI engineering concepts—such as “Which phase do you feel most comfortable with?” or “Assess my knowledge of X.”

Each answer is captured as a plain-text string and processed by the skill runtime in scripts/install_skills.py. The system strips surrounding whitespace and lower-cases the input to ensure case-insensitive matching. Synonyms or alternate phrasings (e.g., “phase 5,” “5,” or “fifth”) are reduced to canonical keywords before evaluation.

Normalizing Responses for Deterministic Mapping

Normalization guarantees reproducibility. Because the mapping logic relies on exact key lookups, the install_skills.py parser converts all responses into normalized tokens before consulting the scoring matrix. This design ensures that two learners providing identical semantic answers receive identical phase recommendations regardless of punctuation or capitalization.

Mapping Answers to Phase Scores

The Knowledge-to-Phase Matrix

The core of the placement logic resides in a knowledge-to-phase mapping table embedded as a fenced JSON block in skills/find-your-level/SKILL.md. This table assigns a numeric score (0 = no knowledge, 1 = basic, 2 = intermediate, 3 = advanced) for each of the 20 curriculum phases against every possible canonical answer.

# Mapping table excerpt from skills/find-your-level/SKILL.md

{
  "answers": {
    "phase-1": [3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "phase-2": [0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    "phase-3": [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    # ... continues for all 20 phases

  }
}

Aggregating the Score Vector

During execution, the select_starting_phase function in scripts/install_skills.py initializes a cumulative score vector of length 20 (one slot per phase). For each normalized answer provided by the learner, the function retrieves the corresponding score array from the mapping table and adds it element-wise to the cumulative vector.

# Simplified aggregation logic from scripts/install_skills.py

def select_starting_phase(answer_keys):
    mapping = load_mapping()  # Parsed from SKILL.md JSON

    scores = [0] * 20         # One slot per phase

    
    for key in answer_keys:
        for i, val in enumerate(mapping.get(key, [])):
            scores[i] += val
            
    max_score = max(scores)
    # Resolve ties by selecting the earliest phase with max score

    start_phase_idx = scores.index(max_score)
    return f"phase-{start_phase_idx + 1:02d}"

Selecting and Persisting the Starting Phase

Tie-Breaking Logic

After aggregation, the algorithm identifies the phase index with the highest total score. In cases where multiple phases share the maximum score, the system defaults to the lowest-indexed phase (the earliest in the curriculum). This conservative approach prevents learners from skipping foundational material when assessment data is ambiguous.

Writing the Placement to LEARNING.md

Once the target phase is determined, the scaffold_workbench.py script persists the decision to a learner-specific file named LEARNING.md in the repository root. This file uses a YAML front-matter block containing the startingPhase key, which downstream skills—such as the course guide—read to route the learner to the appropriate lesson list.

# Persistence snippet from scripts/scaffold_workbench.py

def write_learning_file(starting_phase):
    learning_path = Path("LEARNING.md")
    content = f"""---
startingPhase: "{starting_phase}"
---
"""
    learning_path.write_text(content)

The skills/course-guide/SKILL.md subsequently consumes this file, retrieving the startingPhase value to present the correct sequence of lessons for the learner’s assigned entry point.

Summary

• The quiz aggregates three normalized self-assessment answers into a 20-element score vector using a static JSON mapping table located in skills/find-your-level/SKILL.md.
• Tie-breaking logic defaults to the earliest phase when multiple phases share the maximum cumulative score.
• The select_starting_phase function in scripts/install_skills.py handles all calculation logic without external API calls, enabling offline execution.
• Final placement is written to LEARNING.md by scripts/scaffold_workbench.py, creating a contract that the course guide skill reads to initialize the learning path.

Frequently Asked Questions

What happens if two curriculum phases receive the same aggregate score?

The placement algorithm resolves ties by selecting the lowest-indexed phase (the earliest in the sequence). This conservative strategy ensures learners do not skip foundational content when self-assessment answers suggest ambiguous knowledge levels.

Where is the knowledge mapping data stored?

The scoring matrix lives inside skills/find-your-level/SKILL.md as a fenced JSON block. During skill installation, scripts/install_skills.py parses this block into an in-memory dictionary that maps canonical answer keys to 20-element integer arrays representing phase competency scores.

Can the quiz be taken offline?

Yes. The find-your-level placement quiz requires no external API keys or remote calls. All logic executes locally within the repository using only the files in skills/find-your-level/ and the helper scripts in scripts/, making it fully functional in air-gapped environments.

How does the course guide use the placement result?

After the quiz writes the startingPhase field to LEARNING.md, the course-guide skill defined in skills/course-guide/SKILL.md reads this file to determine which phase’s lesson list to display. This ensures that subsequent learning sessions begin precisely where the placement quiz determined the learner should start.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}