Spec — Lecture production

2026-refresh › lecture-production · feature · created 2026-08-05 · spec · plan.html

The ~28 new and re-recorded lectures for the Advanced JavaScript refresh get made by the simplest possible division of labour: Claude prepares everything sayable and runnable in advance; Asim sits down, rote-reads, selects and presses F8; two local .mov files per take land in a folder. Editing those takes into finished lectures is a separate task (lecture-editing) — this one ends at raw footage.

Problem

P1The new lectures exist only as titles — and Asim can't improvise what he hasn't written since 2018.
~28 lectures (let/const & TDZ, modern arrays, Interview Lab, event-loop re-records, the on-camera intro…) have a row in the production sheet and nothing else. Asim last wrote JavaScript professionally around 2018 — post-ES2017 features are exactly the material he'd be teaching. Without prepared, trustworthy scripts there is nothing to record.
P2Recording historically meant improvising screen and voice at once — that cost is why the course went six years without an update.
Driving an editor, running code, and narrating simultaneously — while being correct — is the expensive, dread-inducing part. The 2026-08-05 specimen test proved the alternative: with a verbatim script and a pre-built workshop file, a lecture reduces to reading aloud and pressing F8, and Asim judged it "I can comfortably record that".
P3New lectures must sit seamlessly beside the imported async course — which is 28 lectures of markdown-workshop VS Code format.
The merged course's dominant code format is Asim's 2018 workshop style: a markdown file with fenced code blocks, select-and-run, output panel. New lectures in a different on-screen format would make the imports look like the odd ones out — the exact inconsistency the refresh exists to remove.
P4The course died by baking in unverified claims — Node-8 behaviour and a dead extension are literally why the flags exist.
The 2018 material taught pre-Node-11 event-loop semantics and a workflow built on an extension that was later abandoned. Every claim in new material must be executed and verified on current Node before Asim speaks it.
script + workshop fileClaude · verified on Node Asim recordsrote-read · select · F8 face.mov + screen.mov→ takes inbox lecture-editingseparate task
This task owns the first three boxes and stops at raw footage; the dashed box is lecture-editing's spec.

Solution at a glance

J0Every lecture Asim records is fully prepared before he sits down, and recording one never asks more of him than reading aloud, selecting, and pressing F8. Claude produces a verbatim script and a pre-built workshop file per lecture (all outputs verified by running them); a pinned VS Code recording profile makes every take look identical; a take produces two local .mov files that accumulate in a folder for the editing task.

Job stories

J1 · When I sit down to prepare a lecture

J1.1Its verbatim script already exists — say/do columns I can rote-read sentence by sentence P1Only titles existAsim can't improvise post-2018 JS P2Improvised recording is the costwhy updates never happened
The approved specimen (curriculum/briefings/let-const-tdz.html) is the template: left column exactly what to say (in Asim's course voice, interview-framed, British English), right column what the hands do, section timings, a traps list of things NOT to say, and continuity references that survive the final lecture order.
J1.2Reading the script leaves me able to teach the topic — preparation and re-skilling are the same activity P1Only titles existAsim can't improvise post-2018 JS
The learn-as-we-build principle from the July spec, carried forward: scripts explain the 2026 truth to a returning-after-years developer, not just recite it — so by the time Asim records, no topic is unfamiliar.
J1.3Every output in the script is real — each code block was executed on current Node before a word was scripted P4Unverified claims killed the courseNode-8 semantics, dead extension
The let/const specimen set the bar: all six demos run and their outputs captured before scripting; error messages quoted verbatim from the actual run. A script may not claim an output nobody has seen.

J2 · When I record a take

J2.1The workshop file is pre-built and every block just runs — blocks numbered to match the script; select, F8, output renders P2Improvised recording is the costreduce it to reading + F8 P3Must match the async course formatmarkdown workshop style
One .md per lecture (specimen: curriculum/examples/let-const/let-const.md) — prose headings for scroll beats, fenced blocks ①–⑥, the odd deliberate live edit with a "try it" comment so the shipped file matches what students download. Code Runner on F8 with the markdown-selection settings proven in the drive spike.
J2.2The recording environment is identical every take — a pinned VS Code profile: layout, fonts, F8, no clutter P3Must match the async course formatfile left, output right
The isolated recording profile from the drive spike survives as the recording environment: workshop file left, Output panel right, pinned theme/font, UI noise removed, warm-up run done off-camera so the Output channel exists. Plain local Node — no containers.
J2.3A flub costs one sentence — pause a beat, re-read the sentence, carry on; takes are never restarted P2Improvised recording is the costretakes must be cheap
The retake convention the editing task depends on: silence gap + re-read marks the cut point; transcript-driven editing finds them. Recording continues; nothing is ever "ruined".

J3 · When a take is done

J3.1One take = two files in the inbox, and I'm finished — face.mov + screen.mov into a known folder; nothing else is asked of me P2Improvised recording is the costrecording ends at raw footage
A per-lecture folder convention (slug-named) the lecture-editing task consumes without explanation. Sync of the two files, retake cuts, overlays, loudness — all downstream, none of it Asim's.

Constraints

Deferred to plan

The definitive recording list and order
Why it must wait: the production sheet still carries the deprecated tier framing; the plan reconciles it into a flat per-lecture list (which S16/S17 lectures stay, final count, script order). As understood now: ~24 new + 4 re-records + the on-camera intro; content selection unchanged unless Asim trims.
The capture app and its settings for the two .mov files
Why it must wait: needs a ten-minute hands-on test on Asim's machine (candidate: QuickTime — one movie recording, one screen recording — any app producing clean .movs works; ScreenFlow explicitly rejected). The plan's recording-setup phase owns the test, plus mic check through the loudness pipeline.
The recording profile's final look
Why it must wait: theme/font choices may borrow from design-system (running simultaneously); a ten-minute call, taken at the recording-setup phase with whatever design has landed by then.

Decisions

Asim records himself — recording automation is rejected
The 2026-08-05 drive spike proved programmatic VS Code driving works mechanically (Demo Time, real selections, F8-identical) but Asim judged the result "doesn't feel like a human". Byproducts (profile, Code Runner settings, capture route) are reused; the robot is not.
Two-file capture: face.mov + screen.mov, local, no ScreenFlow
Asim's explicit choice — simplest possible recording contract; composition happens in editing.
The specimen script format is approved
let-const-tdz (script + workshop file pair): Asim — "I can comfortably record that". All scripts follow it.
Plain local Node — no dev containers
Asim's call; consistency comes from the pinned profile, not containerisation.
Editing is a separate task
Asim's call — "lecture production should be minus the editing"; he's confident editing is solvable later (lecture-editing holds it).

Estimated files / edits

Size: M (repo side) — plus Asim's recording sessions