Authoring style guide

Internal notes for whoever extends this course. Follow the existing repo's CLAUDE.md first; this file only adds course-specific conventions.

File placement

• One index.md per module folder. Folder slug: module-NN-kebab-case-slug/, zero-padded.
• Capstone module is the only folder allowed to ship additional files (rubric.md, optionally a runs/ example).
• All cross-links inside this subtree are relative — ../../lectures/lecture-03-why-…/index.md, never absolute.

Module spine (mandatory)

Every module-NN-…/index.md has these sections in this order:

1. Front-matter blockquote — > Pairs with [Lecture NN](…) plus time, difficulty, prerequisites.
2. # Module NN. <Title>
3. ## Why this module — one paragraph naming the concrete failure this module fixes.
4. ## Concepts — at most two pages. Use the lecture's exact terminology (harness, capability gap, five defense layers, three-layer termination check, WIP=1, VCR, system of record, definition of done). End with → Read [Lecture NN](…) for the long-form treatment.
5. ## Lab — numbered steps with shell commands, file contents in fenced code blocks, expected stdout. If a snippet is ≤ 30 lines, show the whole file. If longer, show a diff.
6. ## Verification — the exact command the learner runs, the success exit code, and the stdout signature.
7. ## Common pitfalls — three to five bullets pulled from real mistakes (or the matching skill's "Gotchas" section under ../.claude/skills/).
8. ## Next — one sentence linking to the next module.

Length targets

Section	Target words
Why this module	80 – 120
Concepts	300 – 500
Lab	400 – 800
Verification	50 – 120
Pitfalls + Next	80 – 150
Total	800 – 1500

If a module is creeping past 1,500 words, split a concept into the matching lecture instead. The course is the companion — the lectures own the depth.

Project consistency rules (noted-cli)

The CLI shape is fixed across all modules. Do not change these without updating every module that references them.

• Runtime: Node.js ≥ 20, TypeScript via tsx, no bundler.
• Package manager: pnpm. The npm substitution is pnpm <cmd> → npm run <cmd> for scripts and pnpm install → npm install.
• Entry point: bin/noted (a thin shim) → src/cli.ts.
• Storage: .noted/*.json, plain JSON, never SQLite or anything binary.
• Tests: node --test against *.test.ts files run via tsx --test.
• Scripts in package.json are named: lint, test, e2e, verify, dev.

Reuse rules

When a resources/templates/ file already exists, link and copy with explicit substitutions, do not paraphrase. Examples:

• "Copy ../../resources/templates/AGENTS.md to your repo root, then change line 1 to # AGENTS.md — noted-cli and the Required Artifacts block to add feature_list.json."
• "Replace the three command variables in ../../resources/templates/init.sh with: INSTALL_CMD=(pnpm install), VERIFY_CMD=(pnpm run verify), START_CMD=(node bin/noted --help)."

This avoids drift between course modules and the canonical templates.

Tone

Second person. Short paragraphs. Concrete numbers. No fluff and no hedging. The existing lectures' register (OpenAI/Anthropic engineering blog) is the target.

Avoid:

• emoji
• "we'll see how…" / "as you can imagine…"
• promises of what future modules cover (link forward instead)
• restating what the lecture already says — link to it

Verification each module ships

Every module's ## Verification section includes a one-line shell command that the learner can paste and run. The course's verify.sh (built in Module 09) eventually unifies all of these into a single pipeline.

The verification must be deterministic — no network calls, no Date.now() in expected output, no race-prone test ordering. If a module needs randomness, it sets a seed.