generate-topic

Generate Topic

Orchestrates the full lesson generation pipeline for one topic. Ensures every downstream step (jargon, quiz, reference, SVG theming, verification) actually happens — not just the lesson writing.

When to use

• Generating a new topic from a MAP.md
• "Completing" an existing topic that's missing artifacts (run against it to fill gaps)
• Any time you want the full pipeline, not just a quick lesson draft

Input

• A workspace path (e.g., library/oidc-rust)
• A topic slug from the workspace's MAP.md (e.g., token-validation-middleware)
• The topic's prereqs should already be complete

The Pipeline (4 Phases)

Phase 1: Research (PARALLEL — fan out 2-4 subagents)

Dispatch simultaneously:

Agent	Task	Output
Domain research	Web search for topic concepts, key facts, 3+ sources	.scratch/research/{slug}.md
Workspace context	Read MAP.md, existing lessons, RESOURCES.md — what's taught, what prereqs cover, avoid repetition	.scratch/research/{slug}-context.md
Source verification	Check top URLs from RESOURCES.md are live, extract key claims relevant to this topic	.scratch/research/{slug}-sources.md

Source-ingested topics: If source-chunks/{domain}.json exists, this topic was derived from a source document. In this case:

• Skip web research — the source chunks ARE the research
• Read the chunk(s) matching this topic's heading from the JSON
• Use chunk content as the authoritative source for the lesson
• When writing SR questions, populate source_section (chunk heading), source_page (chunk page_start), and source_quote (exact passage from the chunk content) on every card

After all return: Synthesize in main context. Resolve conflicts between sources. Determine: what to teach, what to cite, what the learner already knows from prereqs.

Concept hints (opt-in): If source-chunks/{domain}.json exists, run:

python tools/concept_hints.py source-chunks/{domain}.json --topic {slug} --domain {domain}

This produces .scratch/concepts/{slug}.json with:

• Ranked candidate glossary terms (use as starting checklist for jargon, not a mandate)
• L-level suggestions per concept (L1=core recall, L2=practice, L3=analysis — informed by foundational-ness score + prerequisite depth)
• Prerequisite edge suggestions (use for "explain why X depends on Y" question framing)