Topic Buildout Process¶

How to take a topic from zero to fully covered. Follow this order — each step builds on the previous one and is useful on its own if you stop early.

Content Type Build Order¶

Build content in this order for any new or undercovered topic. Each step produces standalone value; don't skip ahead.

Step	Content Type	What It Does	Minimum Bar
1	primer.md	Builds the mental model. Entry point for the topic.	150-300 lines. "Why This Matters" + core concepts + real commands + tables.
2	flashcards	Drives retention via SM-2 spaced repetition.	10+ cards in `cards/<topic>.tsv`. Mix of easy/medium/hard.
3	street_ops.md	Bridges theory to practice. "What do I actually type?"	100-200 lines. Real commands, real output, real workflows.
4	quiz questions	Self-assessment, forces active recall.	3-5 questions in `quiz_bank.yaml` for the topic.
5	footguns.md	What NOT to do. Separates junior from mid-level.	80-150 lines. Real mistakes, real consequences, how to avoid.
6	case studies	Applied diagnosis. "Walk me through troubleshooting X."	1+ case study in `case-studies/<domain>/`.
7	runbooks	On-call playbooks.	1 runbook if there's a common incident pattern.
8	deep dive	Reference-depth material for complex internals.	Only for topics where surface knowledge isn't enough.
9	scenarios	Incident response drills (interactive).	Add to `incident-response.yaml` if there's a realistic triage story.
10	labs	Hands-on, infra-required practice.	Only when we have a runtime environment for it.

Minimum viable topic = steps 1-2 (primer + flashcards). Solid topic = steps 1-5 (primer through footguns). Complete topic = steps 1-7.

Step-by-Step Procedure¶

Step 1: Primer¶

Create training/library/topics/<topic-name>/primer.md
Follow the structure in advanced-bash/primer.md as the template:
# <Topic> - Primer
## Why This Matters — 2-4 sentences connecting to real ops work
## Core Concepts — numbered sections with code examples, tables, gotchas
Real commands with real output (not pseudo-output)
Ops-focused tone: production consequences, failure modes, what you'd see at 3 AM
Length: 150-300 lines. Dense, no fluff.

Step 2: Flashcards¶

Create training/interactive/knowledge/data/cards/<topic>.tsv

Schema (7-column TSV, header row required):

id   category    difficulty  tags    question    answer  source_path

ID format: <category>/<12-char-hex> (use python3 -c "import uuid; print(uuid.uuid4().hex[:12])")
Minimum 10 cards. Target distribution: 3 easy, 4 medium, 3 hard.
Questions should test understanding, not trivia. Good: "What happens when...?" Bad: "What flag does...?"
Answers can be multi-line (use \n within the TSV cell).
Source path: training/library/topics/<topic-name>/primer.md
Validate: python3 tools/validate_flashcards.py

Step 3: Street Ops¶

Create training/library/topics/<topic-name>/street_ops.md
Structure: workflows organized by real task ("Diagnosing X", "Setting up Y")
Heavy on commands, light on theory (primer already covered that)
Include: what the output looks like, what to look for, what to do next

Step 4: Quiz Questions¶

Add to training/interactive/assessments/quiz_bank.yaml
Use the canonical topic key from topics.yaml
3-5 questions, multiple choice, with explanations
Validate: python3 tools/validate_quiz_bank.py

Step 5: Footguns¶

Create training/library/topics/<topic-name>/footguns.md
Structure: numbered footguns, each with "What happens", "Why", "How to avoid"
Draw from real incidents, not hypotheticals

Steps 6-10: As Needed¶

Case studies, runbooks, deep dives, scenarios, and labs are added when the topic warrants them. Not every topic needs all of these. See the existing examples in each directory for format.

Validation After Any Content Change¶

make validate-training-assets          # flashcards, quiz, scenarios, drills
make report-topic-coverage-grid        # regenerate the coverage grid

Regenerate Portal After Registry Changes¶

make validate-registry
make gen-portal
make check-portal-drift