fix(skill): 4 doc-only landmines from real-AI-test feedback (heygen + huly)

Real test agents flagged specific issues their session burned tokens
discovering. Adding lived-experience documentation so future agents
hit these as one-line warnings instead of debug cycles.

step-1-design.md (brand-primary order):
- WAS: "List 8-12 colors..." (no order guidance).
- NOW: "List the brand-primary HEX FIRST. w2h-prep parses DESIGN.md
  and picks the first non-white / non-black hex it finds as the
  brand-primary for tokens.css emission."
- Why: heygen agent had to reorder DESIGN.md so cyan came first;
  prep silently picked the wrong color because the docs didn't tell
  agents about the parser's behavior.

step-5-build.md landmine #10 (sub-comp root background doesn't paint):
- Heygen beat-6 CTA opened on a blank white frame because the root
  div had `background: #050507` CSS which doesn't paint at render
  time (Studio preview paints it; MP4 render doesn't — renderer
  composites against transparency).
- Fix documented: full-bleed child div with `position: absolute;
  inset: 0; background: <color>` paints reliably.
- BAD/GOOD code example showing the wrong vs right pattern.
- Lint can't catch this — known gap, prose-only safeguard.

step-5-build.md landmine #11 (AVIF disguised as .jpg):
- Capture names downloaded images by URL extension, but server may
  serve AVIF to browsers that accept it. AVIF saved with .jpg can
  break headless render (ffmpeg image pipeline may not support AVIF
  depending on build).
- Heygen worker burned a swap cycle discovering learning-development
  .jpg / marketing.jpg were AVIF.
- Workaround documented: `file capture/assets/X.jpg` to detect; use
  different captured asset OR `ffmpeg -i broken.jpg good.png`.

step-5-build.md landmine #12 (SFX CLI gotchas — 4 huly hit):
- CWD drift breaks `source .env` — workaround: stay in project root,
  or use --env explicit path
- zsh doesn't word-split `$CLI sfx ...` — bash does, zsh doesn't.
  Either invoke CLI literally or use `${=CLI}` in zsh
- `sfx add <id>` requires prior `sfx search` (cache-populated, no
  fetch-by-id endpoint) — always search → add
- Some catalog clips are silent / -70 LUFS — `sfx add` prints LUFS
  in the analysis; if it shows ~-70 LUFS, re-search and pick another
  ID

Net: 4 doc additions, zero code change, zero behavior change. All
4 are lived-experience warnings that move "agent discovers via
multi-step debug" → "agent reads one line and proceeds." Each
addressable in fewer than 30 lines of prose.

Followups (not in this commit — separate commits per the verify-
first principle):
- BGM volume hardcode mismatch (assemble-index.mjs:190) — code fix
- voice.start_s hardcode (w2h-prep.mjs:533) — code fix
- Per-beat preview script — new file
- Beat-skeleton boilerplate — new file
This commit is contained in:
ukimsanov
2026-06-11 19:39:12 -07:00
parent 5a6caac18d
commit 4dcc3a6270
2 changed files with 34 additions and 0 deletions
@@ -50,6 +50,8 @@ A flat lookup of the values sub-agents grab while composing beats. Two sub-secti
List 8–12 colors with brand-specific names + HEX + role. Not generic ("Accent 1") but evocative ("Stripe Purple", "Deep Navy", "Slate Border"). The name carries meaning; "blue 4" doesn't.
**Order matters: list the brand-primary HEX FIRST.** `w2h-prep` parses DESIGN.md and picks the first non-white / non-black hex it finds as the brand-primary for `tokens.css` emission. If you list a secondary color first, the wrong color becomes the brand-primary downstream. Order: Primary CTA color → secondaries → supporting → borders.
**Example:**
```markdown
@@ -153,6 +153,38 @@ Every CLI invocation in this skill uses `npx tsx packages/cli/src/cli.ts <cmd>`.
`lint` / `validate` take a DIRECTORY, not a file (`npx tsx packages/cli/src/cli.ts lint .` not `... lint index.html`). `--quality medium` is invalid — the valid set is `draft | standard | high`.
### 10. Sub-comp root `background:` CSS doesn't paint — use a full-bleed child div instead
A composition's root `<div data-composition-id="...">` is the host element the assembler INSERTS into `index.html`. CSS like `.b6-root { background: #000; }` on the root will NOT paint in the rendered video — the renderer composites against transparency. Beat-6 of an early heygen test opened on a blank white frame because of exactly this. The fix is a full-bleed child div that paints the background INSIDE the root:
```html
<!-- ❌ BAD: background on the root won't paint at render time -->
<div data-composition-id="beat-6-cta" style="background: #050507;">
<h1>...</h1>
</div>
<!-- ✅ GOOD: full-bleed child paints the background -->
<div data-composition-id="beat-6-cta">
<div style="position: absolute; inset: 0; background: #050507; z-index: 0;"></div>
<h1 style="position: relative; z-index: 1;">...</h1>
</div>
```
Same rule for gradients, images, or any `background-*` property. The lint won't catch this; it ships looking fine in Studio preview (where root CSS DOES paint) and breaks only at MP4 render.
### 11. Captured assets disguised as the wrong format (AVIF-as-`.jpg`)
The capture pipeline names downloaded images by URL extension (`hero.jpg` if the URL ends `.jpg`), but the SERVER's actual content type may be AVIF — modern image CDNs serve AVIF to browsers that accept it, regardless of URL extension. AVIF files saved with `.jpg` extension can break headless render (Chrome can render AVIF, but ffmpeg's image pipeline may not, depending on build). If a beat references a `.jpg` asset and the render fails to load that frame, check with `file capture/assets/<name>.jpg` — if it reports `ISO Media, AVIF Image`, that's the cause. Workaround: use a different captured asset of the same subject, or convert with `ffmpeg -i broken.jpg good.png`.
### 12. SFX CLI gotchas (cwd drift, zsh word-split, cache miss, dead clips)
The `sfx` command flow has four real friction points lived agents have hit:
- **CWD drift breaks `source .env`** — if you `cd` into a subdir between commands, `.env` relative paths fail. Either use `npx tsx packages/cli/src/cli.ts ... --env $PROJECT_DIR/.env`, or stay in the project root for SFX commands. The local CLI auto-loads `.env` from cwd, so cwd matters.
- **zsh doesn't word-split `$CLI sfx ...`** — if you store the CLI command in a variable (e.g. `CLI="npx tsx packages/cli/src/cli.ts"`), zsh treats `$CLI sfx search "..."` as one giant filename and fails with "no such file." Either invoke the CLI literally (don't store in a variable) or use `${=CLI}` to force word-splitting in zsh. Bash word-splits by default.
- **`sfx add <id>` requires a prior `sfx search`** — the catalog API has no fetch-by-id; `add` reads a per-project cache populated by `search`. If you `add <id>` without searching first, you get "Unknown SFX id." Always search → add. The cache persists per project.
- **Some catalog clips are silent / dead (-70 LUFS)** — occasional misindexed clips return audio that's effectively silent. `sfx add` prints the LUFS in the analysis. If you see something like `-70` LUFS where you expected `-12` to `-20`, the clip is dead — re-search with a different query and pick a different ID.
## 2. Build each composition — USE SUB-AGENTS
**Before dispatching, re-read DESIGN.md and STORYBOARD.md.** You wrote these files earlier in the session and you think you remember them. You don't — not the exact hex values, not the specific font families, not the button border-radius, not the Do's/Don'ts. Re-read them now so you can paste accurate brand rules and beat specs into each sub-agent prompt.