generate-spec

# generate-spec Turn `materials/notebooks/` + `materials/transcripts/` into a `spec.md` that another engineer (or coding agent) can implement end-to-end. ## Steps 0. **Parse `--env=<slug>`, if given.** Pass it only if the user supplied one — never synthesize a slug. With a slug, resolve **both** halves of the overlay relative to `$CLAUDE_PROJECT_DIR`, both in the folder `.claude/skills/generate-spec/references/env-overlays/<slug>/`: `spec-generation-guide.<slug>.md` (the rules) and its `spec-generation-guide.<slug>.runtime.md` companion (the environment's facts). If either is missing, refuse with "No environment overlay named `<slug>`." plus the list of overlays that do exist (the folder names under `references/env-overlays/`). Stop. Without a flag, every step below runs exactly as written and the output is `spec.md`. 1. **Verify cwd is a course folder.** Confirm all of these exist relative to cwd: `materials/notebooks/`, `materials/transcripts/`, `builds/`, `evals/`. If any are missing, refuse with: "Run /generate-spec from inside a course folder — `cd courses/<name>` first." Stop. 2. **Read the guide.** Read `.claude/skills/generate-spec/references/spec-generation-guide.md` relative to `$CLAUDE_PROJECT_DIR` (anchor on the repo root, not cwd). Follow it fully — it is the prescriptive contract for the spec's content, structure, and quality. Do not restate or summarize its rules here; defer to the guide so the two files can't drift. **With `--env=<slug>`:** after reading the base guide in full, also read the overlay's **rules** file resolved in step 0, and follow its precedence rules. Do **not** open the `.runtime.md` companion here — the rules file says when, and reading its facts early corrupts the derivation they are meant to resolve. The base guide is never edited for an environment; the overlay declares what it overrides. 3. **Read every material.** Glob `materials/notebooks/**/*`, `materials/transcripts/**/*` and `materials/slides/**/*`, then read each non-empty file. Slides are optional: most courses have none, and an absent or empty `materials/slides/` is never a reason to refuse — the guide's §4 says how slide evidence is weighted. If the notebooks and transcripts directories are both empty (only `.gitkeep`), refuse with: "No materials found. Add notebooks to materials/notebooks/ and transcripts to materials/transcripts/, then re-run — or optionally run /ingest-course-repo <course-folder-URL> to add the course repo's notebooks and helper.py on top." Stop. 4. **Write spec.md.** Produce a self-contained build-ready spec at `./spec.md` in cwd (overwrite if it exists — this is regeneration, not editing). **With `--env=<slug>`, write `./spec.<slug>.md` instead**, leaving any existing `spec.md` alone — the two are siblings, and their diff is what shows the environment's effect. What the spec must contain and how it handles learner input are governed entirely by the guide — don't duplicate those rules here. The §7 test plan ends with a closing instruction telling the builder to conclude with an infra/structure diagram and the phrase "This is the infra/structure diagram of this app" — `/extract-build-log` uses that phrase as its default closing bookend when slicing the conversation. It's a UX hint, not a system requirement (the slice can also be controlled with `--until="<phrase>"`, and falls back to end-of-transcript if no closing match is found). It sits at the end of §7, not after the Course Context Pack, so the guide's section order holds. 4a. **Mechanical check.** Run `python3 "$CLAUDE_PROJECT_DIR/.claude/skills/generate-spec/scripts/check_spec.py" <the file you wrote>` and fix every finding (citations and reciprocity, dangling references, row-id collisions, guide-section leaks, undefined provenance vocabulary, undeclared fixtures, unknown Not-Included tags), then re-run until it reports 0 findings. The script is deterministic and costs no tokens; a spec that fails it is not ready for the next step. Don't argue with a finding you believe is a parser miss — fix the spec's form so the check passes, since the form is part of the guide's §8 contract. 4b. **Independent audit.** Spawn a fresh general-purpose subagent — never a fork — on an Opus-class model, with the prompt in `references/audit-prompt.md` (fill its two slots: the spec path and, with `--env`, the overlay path). It returns defects only, each with a quoted line. Repair every HARD item and every SOFT item that could make a test fail or force a builder to guess; re-run 4a; then spawn a second fresh auditor. Stop when an audit returns zero HARD items. Two rounds is normal; if a third finds new HARD items, say so in the report rather than looping silently. The generator's own §14 pass is necessary but not sufficient — two generations reported it done and an independent read found 8 and 14 hard defects. 5. **Report.** Tell the user the path written and that they can review, then run /prepare-build when ready. **With `--env=<slug>`:** also print the overlay's Environment Resolutions — every one of the six learner-context dimensions with its resolution — so the removals are visible rather than implied, and remind the user that /prepare-build needs the same `--env=<slug>`. **Without a flag:** if the course already contains a `spec.<slug>.md`, say so and name the flag that regenerates it. Otherwise a course with an environment variant silently gets only its agnostic spec refreshed. ## Don't - Don't write to `builds/`, `evals/`, or `materials/`. - Don't pull in external knowledge to fill gaps in the materials — faithfulness to the course IS what /eval-materials-vs-build measures later. - Don't stop short of the infra-diagram section — it's the default closing bookend `/extract-build-log` looks for; omitting it forces the log slice to extend to end-of-transcript.