Training Metadata Conventions¶

Metadata and tooling conventions for the learner asset system.

Session Runner¶

The session runner (tools/run_training_session.py) builds and runs mixed-mode study sessions from flashcards, quiz questions, and scenarios.

Quick start¶

# List available drills and content
python3 tools/run_training_session.py list

# Run a named drill manifest
python3 tools/run_training_session.py run mixed-daily

# Build an ad-hoc session
python3 tools/run_training_session.py build --mode mixed --count 15
python3 tools/run_training_session.py build --mode flashcard --topic dns --count 10
python3 tools/run_training_session.py build --mode quiz --level L2 --count 5

# View session history
python3 tools/run_training_session.py history

# Or via Make
make run-training-session SESSION_ARGS="list"

Selection strategies¶

weak_first: prioritize topics in _state/weak_areas.tsv
random: uniform random
balanced: equal representation across domains (round-robin)
spaced: weak areas first, then random fill

Deterministic mode¶

Use --seed <int> for reproducible sessions.

Case Study Runner¶

The case study runner (tools/run_case_study.py) provides interactive review of 60 incident case studies across 4 domains.

python3 tools/run_case_study.py list
python3 tools/run_case_study.py run datacenter_ops/raid-degraded-rebuild-latency
python3 tools/run_case_study.py random --domain kubernetes_ops
python3 tools/run_case_study.py index --json

Case studies follow a structured reveal: symptoms → questions → solution → grading.

Progress and Analytics¶

# Full progress report
python3 tools/report_training_progress.py

# Specific views
python3 tools/report_training_progress.py --weakness
python3 tools/report_training_progress.py --recent
python3 tools/report_training_progress.py --recommend
python3 tools/report_training_progress.py --json

# Or via Make
make report-training-progress

State Directory¶

All learner state lives in training/interactive/_state/ (gitignored, learner-local).

File	Schema	Purpose
`session_history.jsonl`	JSON lines (one object per session)	Full session history
`weak_areas.tsv`	topic, asset_type, miss_count, last_seen	Aggregated weak-area tracker
`scenario_log.tsv`	timestamp, scenario_id, topic, difficulty, self_grade	Scenario attempt history
`case_study_log.tsv`	timestamp, case_study_id, domain, self_grade	Case study attempt history
`quiz_log.txt`	freeform (legacy)	Quiz session log

Session history records include: timestamp, session name, seed, items completed, average grade, per-item results with topic/grade, source type counts, topic counts.

Weak areas are updated after each session: grade <= 2 increments miss_count, grade >= 4 decrements it.

Confidence and Difficulty Weighting¶

Flashcard decks carry difficulty (easy/medium/hard). Quiz questions carry level (L0–L3). Scenarios carry difficulty.

Topic Weighting¶

Topic weights live in training/interactive/registry/topics.yaml. Each topic has a domain field used for balanced drill selection and coverage reporting.

Drill manifest convention¶

A drill manifest selects a mixed-mode session. Format (YAML):

name: Daily Mixed Drill
description: 15-minute mixed drill across weak areas
duration_minutes: 15
sources:
  - type: flashcard
    count: 10
    strategy: weak_first
  - type: quiz
    count: 5
    strategy: balanced
  - type: scenario
    count: 1
    strategy: random
filters:
  levels: [L1, L2]
  exclude_topics: []

Asset Discovery¶

Flashcard decks: training/interactive/knowledge/data/cards/*.tsv
Quiz bank: training/interactive/assessments/quiz_bank.yaml
Scenarios: training/interactive/scenarios/*.yaml
Drill manifests: training/interactive/drills/*.yaml
Case studies: training/library/case-studies/<domain>/<case>/
Anki exports: training/interactive/anki/*.tsv

Tags Convention¶

Tags in flashcard decks are comma-separated lowercase strings. Tags in Anki exports are space-separated (Anki convention).