Resolve a roadmap from the issue graph, work out what must be known to write each story's first failing test, subtract what the learner declared and what an earlier story already teaches, order the remainder to introduce the fewest new concepts per step, split any story carrying more than working memory holds into slices, insert a scaffold only where the dependency graph left no freedom, gate the result, and render it as a home page the learner can click into.
What the stage produces is a plan of stubs, not lessons. A stub is a typed contract for one slice — the story it precedes, the concepts it introduces, the concepts it assumes, and pinned pointers to the material a lesson would be written from:
slice: 0007-blocked-by-resolution
story: "#412"
introduces: [topological-order, cycle-detection]
assumes: [issue-graph, sub-issue-linkage]
sources:
- record: "#412 decision record § invariants"
- refuted: "adjacency list vs. edge query"
- exemplar: libs/epic-resolve/src/graph.ts
The pointers are captured here because this is the only phase that reads every issue body, record and diff anyway. A lesson written later then opens three named files instead of searching the repository again, which is what makes deferring the prose cheap rather than merely late. Stubs are also what make the gate reviewable: sequence, splits and scaffolds are the decisions a human makes, and prose is not one of them.
The reading is fanned out. Per-story concept extraction runs as its own unit returning a short structured list, so the planning context holds the lists it must order and subtract and never the bodies they came from. What follows the reading is arithmetic rather than judgement and belongs in the toolkit: the subtraction bookkeeping, the ordering, and a coverage check that every concept a stub assumes is introduced by an earlier stub — a gap there is a plan bug, catchable before a word is written.
Meta
- feature: docs/features/roadmap-driven-learning
- estimate: M
- candidate stories: Resolve a roadmap from an epic issue or a backlog query; A bounded prior-knowledge interview establishes the starting point the repository cannot supply; Per-story concept extraction runs as fanned-out units returning structured lists, not bodies; A stub declares the concepts its slice introduces and assumes, and pins the sources a lesson will be written from; Ordering, slice-splitting under a concept cap, and scaffold insertion; Concept coverage is verified deterministically before the gate; The plan of stubs is approved at a decision-grade gate before anything is written; The approved plan renders as a clickable dependency graph, unwritten slices included; The stage's instructions load by phase, so a planning session never carries the lesson-writing references
- source: decomposition of "A teaching stage that turns a planned roadmap into hands-on exercises, placing the required theory immediately before each one — /nxs.teach, producing a workbook" (2026-08-31); re-scoped 2026-09-01 to produce stubs with pinned sources
Resolve a roadmap from the issue graph, work out what must be known to write each story's first failing test, subtract what the learner declared and what an earlier story already teaches, order the remainder to introduce the fewest new concepts per step, split any story carrying more than working memory holds into slices, insert a scaffold only where the dependency graph left no freedom, gate the result, and render it as a home page the learner can click into.
What the stage produces is a plan of stubs, not lessons. A stub is a typed contract for one slice — the story it precedes, the concepts it introduces, the concepts it assumes, and pinned pointers to the material a lesson would be written from:
The pointers are captured here because this is the only phase that reads every issue body, record and diff anyway. A lesson written later then opens three named files instead of searching the repository again, which is what makes deferring the prose cheap rather than merely late. Stubs are also what make the gate reviewable: sequence, splits and scaffolds are the decisions a human makes, and prose is not one of them.
The reading is fanned out. Per-story concept extraction runs as its own unit returning a short structured list, so the planning context holds the lists it must order and subtract and never the bodies they came from. What follows the reading is arithmetic rather than judgement and belongs in the toolkit: the subtraction bookkeeping, the ordering, and a coverage check that every concept a stub assumes is introduced by an earlier stub — a gap there is a plan bug, catchable before a word is written.
Meta