course-development

Develop a Technical Course

Turn a technical subject into a course that learners can understand, execute, and finish. Own the learning contract: hugo owns the site stack, quality-assurance the test campaign, and playwright browser checks. A course repository's own AGENTS.md overrides this skill wherever they differ.

Workflow

1. Define the learner: state prerequisites, target capability, available time, delivery platform, and accessibility constraints; cut content that does not advance the capability.
2. Write observable outcomes: give each page one primary outcome and a completion signal; closing bullets state what the learner can now do, name, or predict, never attendance.
3. Frame every page: follow page: front matter with an explicit lowercase slug (plus aliases for any previously served URL), an "In one glance" abstract (You will / You need / Time), H2s that name their teaching purpose, ## Your turn with the seven exercise fields, and ## What you can do now ending in a Continue to link.
4. Mirror the source: quote code with {{< include path="<file>" region="<name>" lang="go" >}} over named regions of the shipped reference implementation; paste command output verbatim in text blocks, and derive every quoted count from a generated manifest (data/captures.yaml via mise run docs:captures in the reference course).
5. Make labs executable: state a prediction before the exercise, then declare the Mode (inspect, temporary experiment with target-specific preflight and cleanup, or keep), a preflight command, ordered steps, the gate command that proves completion, and the final state; label offline, live-model, container, Kubernetes, cloud, destructive, and paid commands.
6. Explain diagrams: follow every mermaid diagram with **Diagram in words:** prose; define terms at first use and put the reason beside each command.
7. Check the human surface: verify navigation, reading order, keyboard use, contrast, alt text, mobile layout, and copy-paste on rendered pages with playwright, then run the course's accessibility gate (mise run check:accessibility in the reference course).
8. Validate progressively: run the docs and link gates on the changed page first (mise run check:docs and mise run check:links), then the learner gate from a clean clone (mise run install, mise run doctor, mise run check:core, mise run test), then the definition of done in the course's AGENTS.md.
9. Prepare release acceptance: record the exact candidate, supported platforms, test evidence, known limitations, and correction path, and report the highest proven rung of the proof ladder; publishing remains a separate authorization.