first-span-feedback
The pre-fanout LEARNING GATE. start.sh finishes SPAN 0 alone (through the normal edit/captions/completion chain) before any lane launches, then this skill records a shot-scraper `video` demo of a gene
SKILL.md.claude/skills/first-span-feedback/SKILL.md
GitHubfirst-span-feedback
The one moment a run STOPS on its first delivered span, shows it to a reviewer, and lets that feedback steer the rest of the run — the only pipeline step that can change a skill's code or default so a defect caught on span 0 never recurs. grade-clip/director-pass/fix-cold-open only ever patch one clip's pixels in place; this loop makes the correction stick.
Usage
first-span-feedback.sh <work_id> <clip_stem> <slug> <saved_mp4> [--pane <tmux>]
Invoked by the entrypoint at the Phase 1 → fan-out seam, right after span 0 is saved and before the lanes claim spans 1…N.
How it works
- Record —
build_page.pyfillspage-template.htmlfromclip_00.grade.json(grade/tier + retention signals, failing signal flagged) intowork/<id>/_preview/span0-review.html;storyboard.pyemits ashot-scraper videostoryboard that serves the page over a throwawaypython -m http.server(a realhttp://127.0.0.1origin so<video>autoplays) and plays span 0 through once;uvx shot-scraper videorecordsspan0-demo.mp4. - Review — the demo is sampled into ONE labelled contact sheet (reusing
director-pass/frames.py),build_prompt.pyassembles the sheet +grade.jsonsignals + the transcript, and ONE Claude vision call returns a verdict:{defect, defect_class, signal, where, rationale}.parse_reply.pyextracts it with a deterministic{"defect": false}fail-safe. - Fix + three-gate re-verify + commit (Phases 2-3 — not in this slice) — a flagged systemic defect drives an agentic fixer, a hard re-render → re-grade → re-review accept, and a fixer-path-scoped commit + push.
Phase 1 status: record → review → write span0-feedback.json + .fsfmeta, exit 0. A flagged defect is surfaced only (action: fix_pending); no fixer, no git, no commit yet.
Artifacts — work/<id>/_preview/
span0-review.html— the generated review page.storyboard.yml— the shot-scraper storyboard (server + play scene).span0.mp4/span0-demo.webm/span0-demo.mp4— the served clip copy + the recorded demo.review/sheet.png+prompt.txt+reply.txt— the contact sheet, reviewer prompt, and raw reply.span0-feedback.json— the persisted verdict{work_id, clip, demo, reviewed, verdict{…}, action, phase}.
Knobs
FIRST_SPAN_FEEDBACK(1) —0disables the gate entirely (no_preview/, no review).FSF_MAX_ITERS(1) — fixer review→apply rounds (Phase 2).FSF_FRAMES(12) — frames sampled into the contact sheet.FSF_PORT(8917) — port for the throwaway http.server that serves the review page.FSF_REPLY_FILE— test seam: a canned verdict file stands in for the live reviewer (mirrorsDIRECTOR_REPLY_FILE).FSF_RERENDER_CMD— entrypoint-injected span-0 re-render command; unset ⇒ surface-only, never a code change (Phase 2).
Guarantees
- NON-FATAL — a missing
shot-scraper, a record failure, a parse failure — all leave span 0 and the code untouched and exit 0, so fan-out proceeds on unchanged code. - Idempotent —
.fsfmeta=mtime(span0.mp4)|mtime(grade.json)|FIRST_SPAN_FEEDBACK|v1; a resumed run skips a loop that already ran. - Isolated dependency —
shot-scraperruns throughuvxin an ephemeral env (playwright ≥ 1.61), never touching the vendored 1.60 Node Playwright inlike-subscribe-overlay. - Reuses, never edits —
director-pass/frames.pyfor the contact sheet,_lib/pane.shfor the reviewer dispatch,grade-clip'sgrade.jsonas the gate oracle.