---
name: build-class-deck
description: Build, rebuild or repair ONE live class deck (the "Present" teaching deck for a session in /admin/accelerator) so it passes Ali's authoring contract — no terminal blocks, real commentary on every slide, two disjoint presenter screens, and a run-of-show that actually fits the room. Invoke when Ali says "build the deck for week N", "rebuild Thursday's class", "update session N", "the slide notes are wrong/blank/duplicated", "no terminal codes", "this slide has no commentary", when a class ran over and needs cutting, or before any session that has never been audited. Also invoke to audit every upcoming session at once.
title: build-class-deck
canonical_url: https://skilld.dev/gh/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/build-class-deck
last_updated: 2026-10-08T09:39:34.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install colaberryintern/colaberryenterprise_ai_leadershipaccelerator/build-class-deck`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/build-class-deck`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/colaberryintern/colaberryenterprise_ai_leadershipaccelerator/build-class-deck) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/build-class-deck`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/build-class-deck --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/build-class-deck --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# build-class-deck — the live class deck builder

A **class deck** is the HTML teaching deck an instructor opens with ▶ Present on
`/admin/accelerator`. It is built from three layers, and knowing which layer owns
what is most of this skill:

| Layer | Lives in | Changing it needs |
|---|---|---|
| Authored week content | `backend/src/data/weeks/weekN.ts` | a **deploy** |
| Per-session override | `live_sessions.kit_config_json` | a **DB write only** |
| Generated scaffolding | `kitSpecDaySlides.ts` | a deploy (or `slideNotes`) |

**The override wins.** A session with a `kit_config_json` ignores the week file
for whatever category it overrides. This has burned us: on 2026-09-01 a
load-balancer correction was merged, deployed, and still wrong on screen,
because Session 12's override superseded the corrected week file and had not
been re-applied. **Always verify by reading the database back, never by reading
your diff.**

---

## Ali's settings — these are not suggestions

Every deck must satisfy all of these. They came from him presenting live and
hitting each failure in front of a room.

### 1. No terminal. Everything is a prompt.

> "No terminal codes — everything must be built as a prompt." (2026-08-31, mid-class)

A student never types a shell command. If a step needs a terminal, the prompt
directs **Claude Code to drive the terminal**. Write it so Claude Code
*discovers* facts rather than having them hardcoded — the old Inspector block
hardcoded `build/server.js`, which was wrong for anyone whose server built
elsewhere and was the likeliest way that step failed in the room.

Every prompt should say some version of: *"Run these steps yourself — do not
print commands for me to copy and paste."*

### 2. Every slide has real commentary. No exceptions.

> "This slide doesn't have any commentary — that shouldn't happen. ever." (2026-08-31)

Teach slides carry an authored `script`. **Everything else is generated** —
segment openers, story beats, question slides, cover, break, trailer,
checkpoints — and each ships one hardcoded tip reused identically every week.
Use `KitConfig.slideNotes` to replace them. Beware: a tip that is *true of every
slide of its kind* ("Wait for the pulse to catch up") is boilerplate even though
it is not empty. Say what to verify on **this** slide.

### 3. The two presenter screens must share nothing

> "The pre click and the post click text should be completely different… The preclick should setup the atmosphere and environment before I say what's in the post click." (2026-08-31)

| Screen | When | Contains |
|---|---|---|
| Arrival (pre-click) | landing on the slide | SITUATION · ROOM · MOOD · OPEN · DO · NOTE |
| Read (post-click) | diagram full-screened | the slide's `body`, plus SAY lines |

`splitScript` enforces it. Colours: **SITUATION** violet · **ROOM** blue ·
**MOOD** green · **OPEN** gold · **SAY** gold · **DO** blue · **NOTE** grey.
OPEN shares SAY's gold deliberately — they never share a screen, and both mean
"words you speak".

Write scripts as tagged lines. Untagged still renders (one grey block), so it is
a warning not a failure — but colour-coding is the point.

```
SITUATION: where we are in the story; what just happened
ROOM:      what is on screen, what to have ready
MOOD:      the energy to set before speaking
OPEN:      the first words out of your mouth
DO:        an action — run it, ask it, wait
SAY:       spoken verbatim
NOTE:      commentary, pacing, what to watch for
```

### 4. Shorter than authored. Volume is what makes a class overrun.

Weeks 4 and 5 both ran past the end and never reached the last two segments.
The cause was **not** pace:

| | W4 authored | W4 as presented | W5 | W6 authored | W6 rebuilt |
|---|---|---|---|---|---|
| teach slides | 22 | 22 | 22 | 21 | **16** |
| body prose | 13,787 | 11,450 | 15,435 | 14,903 | **8,762** |
| live builds | 4 | 4 | 4 | 4 | **2** |

**Rules that follow:**
- **At most TWO live builds** in a 30-minute micro-build window. The rest
  stay prompts (see §6 — never `kind: 'review'`) but light ones: a survey,
  an audit of a file they already have, a command *composed but not run*.
  The reasoning is written *into the prompt as comments*.
- **Never cut questions.** They cost 1–2 minutes each and they hold the room.
  Cut prose and live builds instead.
- **Move the best moment early.** The `challenge` (95–110) and `trivia`
  (110–117) segments are where the overrun lands. Anything you care about goes
  in `architecture` (~min 45) instead. Leave a genuinely expendable
  self-diagnosis poll in the tail.

### 5. One narrative spine everyone can follow

> "Make sure you have an overall narrative, good examples, and questions throughout to keep them engaged… have a great story everyone can understand and follow."

Pick a spine a non-engineer would understand and restate it in the roadmap
slide, in every segment eyebrow, and at the close. Week 6 used **the night
shift**: a helper that works while you watch becomes a worker who works while
you sleep, and the four protocol upgrades became the four things any night
worker needs — no keys of their own (sampling), a duty to call in
(notifications), a floor they stay on (roots), a posting somebody signed
(transport).

Story beats are human and specific and end with a **punch** aphorism. Polls have
four plausible options, a `reveal` that reasons, and a `presenterTip` that says
how to *run* it ("expect the room to split hard", "send mentors to the last two
options immediately").

### 6. Teach in the prompts, even where nothing is built — and never `kind: 'review'`

> "Allow teaching in the prompts even if we aren't building something with that step."

> "All the prompts should be prompts in the code section. I don't like these review together scripts. They should all be prompts where we can at least learn something." (2026-09-14, as Session 16 started)

**`kind: 'review'` is retired.** A read-along block teaches nothing the room
can act on. Every code block is `kind: 'paste'`, `pasteWhere: 'Claude Code'`,
with `expectedResult`, `stopCondition` and `rescue`. Where the authored slide
was a file to read, the prompt makes Claude Code *build or inspect the same
thing in the student's own repo* and explain it back. This includes hand-pasted
config — the Week 8 YAML workflows hardcoded `npm ci` / `npm test` and would
have failed every non-Node project in the room; as prompts, Claude Code writes
them against the project's real commands. Even the "break it on purpose"
anti-pattern is a prompt: reproduce it *safely* (throwaway branch, guard
removed then restored, no push), never with `--dangerously-skip-permissions`.
Put the *why* inside the prompt as comments:

```
1. Declare the logging capability when the server is constructed.
   # WHY: without the declaration the client drops every log message on the
   # floor. Nothing errors. You will think your code is broken and it is not.
```

### 7. Write for the room that will actually be there

If a Monday was a holiday, the Thursday deck must never say "as we said on
Monday". Say the shape of the night out loud at the top, including a non-standard
finish time.

---

## Hard traps

**Slide ids are `<segmentId>-<index>` and are NOT unique.** The cover and the
cold-open segment slide are both `cold-open-0`. Key `slideNotes` as `kind:id`
to disambiguate. **Never renumber slide ids — the live poll key IS the slide
id**, so renumbering orphans votes mid-class.

**`teachToSlides` filters by segment id.** A slide tagged with a segment that is
not in the run-of-show renders **nowhere**, silently. Valid Architecture Day:
`cold-open, checkin, business-problem, architecture, deconstruct, reset,
micro-build, challenge, trivia, trailer`. Build Day: `result-preview, readiness,
build-map, guided-build, reset, failure, demos, broadcast, cta`.

**Checkpoint slides are not overridable.** The buildmap and CP0..CPn render from
the week's `buildMap`/`checkpoints` in `classSessionPlan.ts`. Week 4's Build Day
was rebuilt around five prompts while five checkpoint slides still advertised
"8 prompts". Either keep the checkpoint count, or set
`checkpointsEnabled: false`. **The rail's numbering wins over the eyebrows**:
Week 8's rail read CP0 ready · CP1 commands + hook · CP2 headless · CP3 CI while
the authored eyebrows counted CP1…CP4 — the overridable side (eyebrows, the
roadmap slide's list) is the side you change (`session17-week8-thursday.js`).

**The Architecture Story slide has no body.** Its read screen is SAY lines
alone, so its slideNote must carry a node-by-node spoken walk of the diagram
or the phone says "keep talking from the diagram" (Ali, 2026-09-14:
"Architecture story's should have commentary explaining it"). Every week's
`architecture:architecture-0` needs this; `session16-generated-notes.js` is the
reference. Check any generated slide with `body === ''` the same way.

**Arrival notes one slide behind the projector = broadcast ordering, not
content.** Fixed in #2561 (deck stamps `deck_id`+`seq`, server refuses a late
write, deck heartbeats every 5 s). If it recurs, read `session_broadcast` while
the deck sits on a known slide — a Present tab opened before that deploy is
unstamped and still last-write-wins.

**The container's `/app/*.js` copies are wiped by every recreate.** A morning
deploy erased `audit.js`; re-`docker cp` before running anything. The data in
`kit_config_json` survives.

**`detectDayKind` matches the literal phrase `architecture day`.** For a
combined class, "Week 7 · Architecture **+ Build** Day" resolves to `build`
(correct, keeps checkpoints); "Architecture Day + Build Day" would flip it to
`architecture` and silently drop the entire build.

**The run-of-show scales proportionally.** At 150 minutes `build-map` is still
only 12 minutes. Put long teaching inside `guided-build` (63 min) or the pace
tracker reads as badly behind all night.

**`.js` under `backend/src/scripts` never reaches `dist`** (no `allowJs`). Deck
composer scripts run from your laptop or via `docker cp`, never from the image.

---

## The process

### Step 1 — audit first, always

```bash
scp backend/src/scripts/auditClassDecks.js root@95.216.199.47:/tmp/audit.js
ssh root@95.216.199.47 'docker cp /tmp/audit.js accelerator-backend:/app/audit.js \
  && docker exec accelerator-backend node /app/audit.js'
```

Runs against the **rendered** deck for every scheduled session. `--all` includes
completed/cancelled; pass a session id for a verbose single-session report.
Exit 1 on any hard failure, so it can gate a deploy.

### Step 2 — decide the layer

- Wrong/stale content that every future cohort should get fixed → **edit
  `weekN.ts`**, needs a deploy.
- Shape of one specific night (cutting, reordering, a combined class) →
  **`kit_config_json` override**, DB write only.
- Commentary on generated slides → **`slideNotes`**, DB write only.

Prefer the week file. An override is a fork you have to maintain.

### Step 3 — compose, do not transcribe

For a big rebuild, write a composer script that requires the authored
`WEEK_N_PACK` from `dist` and assembles the override from slides that already
exist. See `session15-week7-combined.js`: it lifted six architecture slides from
a cancelled Monday, re-segmented them to `guided-build`, and prepended them to
Thursday's authored build slides. No 19-slide hand-copy to drift from source.

### Step 4 — apply

```js
const { saveKitConfig } = require('/app/dist/services/sessionKitConfigService');
saveKitConfig(sessionId, config)   // mergeKitConfig fills unset categories with defaults
```

`null` for a category means "use the authored defaults". An `overrides` array is
a **full replacement**, never a merge.

### Step 5 — verify from the database

Rebuild the spec via `getKitConfig(sessionId)` — not your in-memory object — and
re-run the audit. Then confirm the presenter phone:

```js
const { getPresenterNotes } = require('/app/dist/services/sessionLiveStateService');
```

It derives both screens server-side from the session's own spec, so **tab age no
longer matters** — if notes look wrong, suspect content, not a stale Present tab.

### Step 6 — rollback

```sql
UPDATE live_sessions SET kit_config_json = NULL WHERE id = '<session>';
```

Restores the authored deck exactly.

---

## Reference files

| What | Where |
|---|---|
| Audit tool | `backend/src/scripts/auditClassDecks.js` |
| Architecture Day rebuild | `backend/src/scripts/session-decks/session12-week6-monday.js` |
| Commentary for generated slides | `backend/src/scripts/session-decks/session12-slide-notes.js` |
| Composed combined class | `backend/src/scripts/session-decks/session15-week7-combined.js` |
| Script + prompt + eyebrow overlay (compose, don't transcribe) | `backend/src/scripts/session-decks/session17-week8-thursday.js` (Build Day), `session16-week8-monday.js` (Architecture Day) |
| Generated-slide notes incl. the Architecture Story walk-through | `backend/src/scripts/session-decks/session16-generated-notes.js`, `session17-generated-notes.js` |
| Broadcast ordering (deck→phone) | `classKit/kitDeckScript.ts` (`broadcastCurrent`), `sessionLiveStateService.ts` (`broadcastConflictClause`) |
| Contract enforcement | `classKit/kitHtml.ts` (`splitScript`), `classKit/kitConfig.ts` (`slideNotes`) |
| Two-screen renderer | `services/sessionKitDocService.ts` (`paint`, the category CSS) |
| Phone derivation | `services/sessionLiveStateService.ts` (`getPresenterNotes`) |

## Definition of done

- [ ] `auditClassDecks.js` reports **0 failures** for the session
- [ ] Verified by reading `getKitConfig` back from the database, not from a diff
- [ ] Every code block is a Claude Code prompt — `kind: 'paste'`, no `review`, no pasted config files
- [ ] The Architecture Story (and any generated slide with no body) has SAY lines
- [ ] Build Day eyebrows use the rail's checkpoint numbers
- [ ] Every slide has commentary written for *that* slide
- [ ] Arrival and read screens share no text
- [ ] Checkpoint count still matches the buildmap (Build Day)
- [ ] Slide count and prose are **below** the authored baseline, not above
- [ ] Session log entry in `docs/sessions/CC-<id>.md`
