docs(skills): add pre-build gate to changelog-video SKILL.md#2669
Conversation
Adds an explicit Step 0 above the pipeline that spells out the concrete file copies (fonts, bgm, ffmpeg-encoded bg-pattern, master-skeleton.html) before any composition HTML is written. Extends the anti-patterns table with the three failure modes James caught on the Jul 13-20 weekly run: starting from a prior video's index.html, hand-crafting @font-face / WebGL shader / custom BGM, and shipping without a CloudFront invalidation after the S3 replace. Why: the previous SKILL.md said "follow references/build-spec.md exactly" in step 5, but that lets an agent read the build-spec after already writing composition HTML on the wrong scaffold. Ships of the Jul 13-20 video went through three off-brand iterations before I finally started from master-skeleton.html (Jake called v3 "trash" — the skill's assets, fonts, and scaffold ARE the brand, not the SKILL.md prompt on its own). The three added anti-patterns are the concrete traps: agents will keep starting from prior-project templates unless the skill explicitly bans it. Mirrors to .agents/skills/ (Codex CLI) and .claude/skills/ (Claude Code) byte-identical, per the skill-mirror gate.
vanceingalls
left a comment
There was a problem hiding this comment.
LGTM.
What I checked:
- Both mirrored SKILL.md diffs are byte-identical (per PR body + independent diff read). Consistent with the mirror gate.
- All referenced paths exist on
main:.claude/skills/changelog-video/assets/{fonts/,bgm.mp3,bg-pattern.mp4},examples/master-skeleton.html,references/build-spec.md. Step 0'scptargets are real. - Ran the anti-patterns against the failure narrative: (1) prior-video
index.htmlreuse → covered by the master-skeletoncp; (2) hand-crafted@font-face/ WebGL / BGM → covered byassets/verbatim copy; (3) missing CloudFront invalidation → orthogonal delivery-side trap, worth calling out separately. - ffmpeg command's
bg-pattern-<TOTAL>s.mp4output name matches theassets/bg-pattern-<dur>s.mp4convention in the existing "Project layout" section. - No conflict with existing step 5 ("Build") — Step 0 supplies the scaffold + Step 5 fills into it; the framing paragraph makes that division explicit ("step 5 fills placeholders inside the already-copied
project/index.html").
One nit (non-blocking).
The Step-0 explanatory paragraph enumerates placeholders as <RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, scene bodies. <RANGE> (3×) and <TOTAL> (7×) exist literally in master-skeleton.html, but the actual per-cut tokens are <CUT1>, <DUR1> (indexed) — and the skeleton also uses <THEME> + <HEADLINE> which the paragraph doesn't mention. Reads fine as metasyntactic (_N = "for the Nth cut") but a future agent doing a literal grep would come up empty on <CUT_N>. If you want to tighten this in a follow-up: swap for <CUT1..N> / <DUR1..N> and add <THEME>/<HEADLINE> to the "scene bodies" phrase. Not worth blocking on.
Ship it — the durable fix that would have prevented three off-brand iterations on the Jul 13-20 run.
Review by Via
* docs(skills): make captions non-optional in changelog-video The Jul 13-20 build shipped without captions because the pipeline had two soft failure modes: - Empty vo-words.json from the TTS provider was silently accepted, so align-captions.mjs had nothing to align. captions.json was never produced. - Step 5 tolerated the master-skeleton's LINES array staying empty. The build lint-checked and validated clean, but the caption rail rendered no text. This adds three hard gates on top of the existing scaffold: - Step 4 adds a whisper forced-alignment fallback so a missing TTS timestamp payload no longer breaks the caption pipeline. Whisper only supplies timings; captions still use the DISPLAY layer from script-tokens.json. - Step 5 flags an empty LINES array as a shipped bug and shows the exact IIFE-input shape it expects. - Step 6 adds gate 5: sample 3-4 frames across the VO window and confirm visible caption text on each. If any spoken window renders no caption, the build is red. Anti-patterns table gets two rows covering the empty-LINES and missing-word-timings failure modes. .claude and .agents mirrors stay byte-identical. Follow-up to #2669 (pre-build gate); paired with the v5 rebuild that retrofitted captions onto the shipped Jul 13-20 video. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(skills): bump changelog caption size to 32px for phone-screen legibility 25px reads too small at 1080² when the video is viewed on a phone without zoom. Bumped to 32px (font-size 25→32, top 1002→990, height 40→52, alpha .92→.94) so captions carry across small-screen playback. Change is CSS-only on the master-skeleton; existing per-scene chrome and layouts are untouched. Retrofitted the Jul 13-20 v6 build with the same values (identical CSS block) so the shipped video and the future default match. .claude and .agents mirrors stay byte-identical. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(skills): sync caption position refs to top: 990 across SKILL.md + build-spec Miga caught: the master-skeleton bump to top: 990 / 32px / height: 52 was not reflected in the SKILL.md prose or build-spec.md. All three files now name the same values so the doc, gate, and code stay consistent. Also clarifies build-spec.md's caption-rail line to point at SKILL.md step 5 as the source of the LINES-populated requirement. .claude and .agents mirrors byte-identical. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs(skills): sync script-voice.md caption rail to top: 990 / 32px Third and final stale reference to top: 1002 / 25px — script-voice.md was still stating the pre-bump values. Now matches master-skeleton.html, build-spec.md, and SKILL.md. Also bumps the 'keep critical small text out' guidance from ~80px to ~100px to reflect the slightly taller caption rail. Full-directory sweep confirms zero remaining occurrences of 1002 or 25px across .claude/ and .agents/ skill mirrors. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
What
Adds an explicit Step 0 above the existing pipeline in
.claude/skills/changelog-video/SKILL.md(and the mirrored.agents/skills/changelog-video/SKILL.md) that spells out the concrete pre-build file copies before any composition HTML is written:cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3ffmpeg …re-encode of<SKILL_DIR>/assets/bg-pattern.mp4to the total durationcp <SKILL_DIR>/examples/master-skeleton.html project/index.htmlreferences/build-spec.mdend-to-end BEFORE writing contentAlso extends the anti-patterns table with the three failure modes hit on this week's Jul 13-20 weekly run:
index.html@font-face/ WebGL shader / custom BGME2BSLVSZ7FG3U0)Why
The previous SKILL.md said "follow
references/build-spec.mdexactly" in step 5. That lets an agent read the build-spec after already writing composition HTML on a wrong scaffold — which is exactly what happened on the Jul 13-20 run: three off-brand video iterations (WebGL shader background, JetBrains Mono fonts, blue accents) before finally starting frommaster-skeleton.html. Jake (skill author) called v3 "trash" — the assets, fonts, and scaffold ARE the brand, not the SKILL.md prompt on its own.The three added anti-patterns are the concrete traps: agents keep starting from similar-looking prior-project templates unless the skill explicitly bans it and points at the exact
cpcommands.Test plan
bun scripts/lint-skills.ts— 31 skill file(s), 0 issues (fixed inline-backtick>false positives on the first attempt via rewording)node scripts/check-skill-mirror.mjs— 24 files byte-identical across.claude/skills/and.agents/skills/bun run lint— 0 warnings, 0 errorsbun run format:check— all matched files use the correct formatbunx fallow audit --base origin/main --fail-on-issues— ✓ No issues in 2 changed filesContent-only change; no scripts or assets touched.
Follow-up
Home's weekly cron (
cron_dfd99766) — I've sent the corresponding cron-prompt update (via send_to_teammate) so next Monday's autonomous run picks up the pre-build gate before this PR merges. This PR is the durable skill-level fix; the cron update is the specific-cron-flow fix. They're additive.