rootnode-academy/docs/COURSE_AUTHORING_STANDARD.md

# Course Authoring Standard

Phase 6A §11 — the standard every future RootNode lesson/module must follow, so a future Claude
Code session or a human instructor can author content consistently. The module at
`content/root/root-10-kubernetes-troubleshooting-observability/m01-health-probes/` (backing
`root-10-m01-health-probes-and-troubleshooting`) is the reference implementation — when in
doubt, read it before writing new content.

## 1. Target learner

State explicitly, in the module's Postgres `description` (not buried in prose): who this is for
and what they're assumed to already know. root_ targets ages ~15-18+ through adult learners
(see `docs/PHASE6A_ROOT_COURSE_FOUNDATION.md` §1) — write at a level that respects that range;
don't write down to it.

## 2. Prerequisites

Declare real prerequisite course/module ids in the `prerequisites` column, not prose alone (see
`docs/COURSE_CONTENT_MODEL.md` §5 for how locking derives from this). If a module assumes a
concept the platform doesn't yet teach anywhere, say so explicitly in the module description
rather than silently assuming it.

## 3. Measurable objectives

3-5 objectives per module, stored in the `objectives` column, each a sentence that starts with a
verb describing an observable capability ("Diagnose...", "Configure...", "Explain..."), not a
topic list ("Probes"). A learner (or an instructor) should be able to look at an objective and
know whether it was met.

## 4. Estimated time

Set `estimated_duration_minutes` per activity and let the module/course total derive from the
sum — don't hand-guess a module-level number that doesn't match its activities. Time estimates
are honest guesses, not commitments; revise them once real completion-time data exists (the
mechanically-mapped modules' per-scenario 15/20/30-minute estimates in
`022_course_content.sql` are explicitly flagged as a rough heuristic for exactly this reason).

## 5. Concept explanation (the `lesson` activity)

Explain the underlying concept BEFORE any lab is presented — this is the module's core
pedagogical premise (see `docs/PHASE6A_ROOT_COURSE_FOUNDATION.md`'s "core product principle").
Cover: why the concept/mechanism exists (the problem it solves), the mechanism itself, and
common real-world mistakes. Use concrete, runnable examples (`kubectl` output, YAML snippets)
over abstract description wherever possible.

## 6. Demonstration

Show the concept in action with a worked example BEFORE asking the learner to do it themselves.
A demonstration activity should include what the learner would actually SEE (real-looking
command output), not just a description of what would happen.

## 7. Guided practice (the `guided_exercise` activity)

Lower-stakes practice with a visible worked answer to check against (paper/scratch-file
exercises are fine — see the gold module's readiness-probe exercise). The goal is committing to
an answer and comparing, not passively reading a correct one first.

## 8. Independent practice → lab mapping

A `lab` activity references an EXISTING `scenario_id` — never invent duplicate lab content when
an existing scenario already teaches the concept (check `docs/ROOT_CURRICULUM_INVENTORY.md`
first). Write a short `content_path` intro (see the gold module's `05-lab-intro.md`) that
connects what was just taught to the incident the student is about to solve, without handing out
the scenario's own hints/solution — the Lab's own progressive hints stay the only place the
actual answer path lives.

### Classifying near-duplicate or advanced scenarios (Phase 6B)

When two scenarios teach essentially the same concept (e.g. `pod-security-context` and
`cks-pod-security-context`), don't wire both as required core labs — pick the better-fitting one
as CORE and mark the other `is_required = false` as INDEPENDENT PRACTICE (see
`docs/ROOT_CURRICULUM_COVERAGE_MATRIX.md`'s "duplicate concepts identified" for worked examples).
Likewise, a genuinely harder or more niche scenario (CKS-exam-style, a less commonly needed
skill) belongs as `is_required = false` GUIDED/ADVANCED practice, not force-fit into the
required core path just because it exists — see `docs/COURSE_CONTENT_MODEL.md`'s optional-vs-
required section for how this affects module completion.

## 9. Knowledge check

A handful of self-check questions with answers shown inline (not a graded exam — that's what the
assessment engine is for). Use plain Markdown (`*Answer:*` after each question), not raw HTML
`<details>` — `react-markdown` renders this repo's course content and does not have `rehype-raw`
enabled, so raw HTML tags render as literal text, not a collapsible element.

## 10. Reflection

A reflection activity consolidates and connects to real-world judgment — it is not a second
knowledge check. Ask "why does this matter beyond this one Lab," not "what did you just do."
Include a "Real Ops takeaway": a concrete prevention/production practice a learner could apply
on a real team.

## 11. Instructor notes

Every activity type CAN have an `## Instructor Notes` section (see
`docs/COURSE_CONTENT_MODEL.md` §3); a `lesson`/`demonstration`/`guided_exercise`/`reflection`
activity SHOULD have one. At minimum include: approximate timing, one likely misconception to
watch for, and (where relevant) a discussion question or optional extension activity. Keep it
actionable — a bullet list an instructor can glance at mid-class, not a second essay.

## 12. Accessibility/readability

Plain Markdown only (headings, lists, code fences, bold/italic, tables) — no content that
depends on color alone to convey meaning, no ASCII art carrying information a screen reader
would lose. Write short paragraphs; prefer lists over dense prose for anything enumerable
(steps, mistakes, questions).

## 13. Terminology rules

Match the terminology the scenario JSON and existing Platform UI already use exactly (e.g.
"readiness probe," not "health check probe" — check `scenarios/data/<id>.json`'s own
`description`/`hints` for the canonical phrasing before introducing a lesson's own term for the
same thing). Define a term the first time it's used in a module; don't assume a prerequisite
module's terminology carried over without a one-line reminder.

## 14. Versioning

Bump the `version` integer on courses/course_modules/module_activities by hand on any semantic
content edit — same convention `assessment_definitions`/`programs` already use. A version bump
is informational only in Phase 6A (nothing snapshots against it the way an assessment session
snapshots its definition version) — it exists so a future phase can detect "this changed since a
student last saw it" without re-deriving that from `updated_at` alone.

## 15. Review/testing requirements

Before marking a module `status = 'ready'`:

- Every activity's `content_path` file must exist and load (verify via
  `platform/api/src/content.js`'s `loadContent`, or just hit the admin curriculum API and check
  `body` is non-empty).
- A `lab` activity's `scenario_id` must be a real, existing scenario id.
- An `assessment`/`capstone` activity's `assessment_definition_id` must be a real, active
  `assessment_definitions` row.
- Walk the module once as a self-paced student end to end (lesson → ... → lab → reflection),
  and once through the instructor Curriculum view, before shipping — this is what
  `e2e-phase6a.js` and `infra/scripts/drills/test-phase6a-course-rehearsal.js` automate for the
  gold module; extend one of them (or add a new phase-scoped test) for future modules rather
  than skipping this step.