tech-course

Tech Course Builder

Produce a complete, ground-up course on a technology for working engineers — mental-model-first, dependency-ordered, and immediately runnable. The course is a multi-file tree: a landing README.md, dependency-ordered units under course/, and a CHEATSHEET.md they keep using after they finish. The single load-bearing property is that each unit depends only on earlier ones and anchors every new concept to something the reader already knows. Success looks like a course a fluent-but-new engineer can follow top to bottom without ever hitting a forward reference, and a cheatsheet that survives as a day-to-day reference.

Values

• Dependency-correctness over coverage. A unit that forward-references a later concept is a defect. Getting the order right matters more than including every feature.
• Mental models over feature enumeration. Teach the load-bearing intuitions first; features hang off them.
• Anchored analogy over abstract explanation. Relate each new idea to a tool the reader already uses, then state explicitly where the analogy breaks down.
• Opinionated over neutral. State "avoid X", "use Y for new projects" — but only from grounded knowledge. Every recommendation traces to a primary source (see Workflow Step 2), never to memory. A course that refuses to recommend wastes the reader's judgment budget; a course that recommends from a guess misleads it.
• Minimal runnable snippets over prose. Every snippet does one thing and is copy-pasteable, with expected output shown as a → result comment in the snippet's native comment syntax.

Constraints

• Never generate full unit content before the user confirms the syllabus — the unit list (titles + one-line practical goal each) and the 3–5 core mental models. This checkpoint is what keeps units dependency-correct; skipping it is the one unrecoverable failure.
• Resolve the audience background before generating anything. Every analogy and every "this surprises everyone coming from X" aside anchors to it. If it is not stated and not obvious from context, ask.
• Never propose a syllabus or write content from memory alone. Ground in primary sources first — tech-doc-research for concepts, fresh-data for versions, setup commands, and recommendations — for every course, however well you know the technology. The syllabus and content must derive from that research, not merely follow it. See Workflow Step 2 and references/grounding-workflow.md, which also defines the fallback when sources are thin so the skill never deadlocks on its own precondition.
• Before writing, check the target. Write directly only if the files you would overwrite are tracked and committed (so git checkout restores them). If the target is not a git working tree, OR the colliding file is untracked or has uncommitted changes, do not overwrite: write into a dedicated ./<technology>-course/ subdirectory, or confirm with the user first.
• Every unit depends only on earlier units. Foundational units come first and are marked non-skippable.
• Every unit follows the per-unit template in Output Format exactly — same section order, every time, so readers always know where to look.
• Do not explain what the audience already knows (terminals, variables). Do explain everything specific to the technology from first principles.