Skip to content

puntorigen/avatar-skills / onboarding-script

onboarding-script

Verified

scripts/check_episode.py

View on GitHub
#!/usr/bin/env python3
"""Validate onboarding episode beat sheets before rendering.

Prints a PASS/FAIL/WARN report per file. Exit code 0 if there are no FAILs across
all inputs (WARNs allowed), 1 otherwise. Pure stdlib.

    python3 check_episode.py onboarding/acme/episodes/*.episode.json
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

VALID_KINDS = {"talking_head", "demo", "broll"}
SENTENCE_MAX_WORDS = 14      # caption-friendliness: split longer sentences
WORDS_PER_SEC = 2.6          # spoken pace ceiling for the length sanity check


def words(text: str) -> int:
    return len(re.findall(r"\b[\w'’]+\b", text or ""))


def is_todo(text: str) -> bool:
    t = (text or "").strip()
    return not t or t.lower().startswith("todo")


def long_sentences(text: str) -> list[str]:
    out = []
    for s in re.split(r"(?<=[.!?])\s+", (text or "").strip()):
        if words(s) > SENTENCE_MAX_WORDS:
            out.append(s)
    return out


def check_episode(path: Path) -> tuple[list[str], list[str]]:
    fails: list[str] = []
    warns: list[str] = []
    try:
        ep = json.loads(path.read_text(encoding="utf-8"))
    except Exception as exc:  # noqa: BLE001
        return [f"could not read JSON: {exc}"], []

    for field in ("id", "slug", "order", "title", "language", "target_seconds"):
        if ep.get(field) in (None, ""):
            fails.append(f"missing top-level field '{field}'")

    # slug should be zero-padded-order + id-ish.
    order = ep.get("order")
    slug = ep.get("slug") or ""
    if isinstance(order, int) and not slug.startswith(f"{order:02d}"):
        warns.append(f"slug '{slug}' doesn't start with the zero-padded order '{order:02d}_' (breaks file ordering).")

    beats = ep.get("beats", []) or []
    if not beats:
        fails.append("no beats")
        return fails, warns

    seen_ids = set()
    has_vo = False
    for i, b in enumerate(beats, start=1):
        bid = b.get("id", f"#{i}")
        if bid in seen_ids:
            warns.append(f"duplicate beat id '{bid}'")
        seen_ids.add(bid)

        kind = b.get("kind")
        if kind not in VALID_KINDS:
            fails.append(f"beat '{bid}': kind '{kind}' not in {sorted(VALID_KINDS)}")

        narration = b.get("narration", "")
        if is_todo(narration):
            fails.append(f"beat '{bid}': narration is empty/TODO")
        else:
            has_vo = True
            if "[TO CONFIRM]" in narration:
                warns.append(f"beat '{bid}': narration has an unresolved [TO CONFIRM] — verify or ask before shipping.")
            for s in long_sentences(narration):
                warns.append(f"beat '{bid}': long sentence ({words(s)} words) — split for captions: \"{s[:60]}...\"")

        if kind == "demo":
            demo = b.get("demo") or {}
            if not (demo.get("url") or "").strip():
                fails.append(f"beat '{bid}': demo has no url (the recorder needs a URL to open).")
            if is_todo(demo.get("intent", "")):
                fails.append(f"beat '{bid}': demo has no intent (natural-language description of the recording).")
        elif kind == "broll":
            if is_todo(b.get("broll", "")):
                warns.append(f"beat '{bid}': broll visual not described.")

        if is_todo(b.get("caption", "")):
            warns.append(f"beat '{bid}': no caption text (burned-in captions boost retention).")

    if not has_vo:
        fails.append("no beat carries a voice-over (narration) — nothing to narrate/tile.")

    # Length sanity vs target.
    total_words = sum(words(b.get("narration", "")) for b in beats if not is_todo(b.get("narration", "")))
    target = ep.get("target_seconds")
    if isinstance(target, (int, float)) and total_words:
        est = total_words / WORDS_PER_SEC
        if est > target * 1.25:
            warns.append(f"VO is ~{est:.0f}s vs target {target}s — trim to keep the reel tight.")

    # Storyboard tiling sanity: scene.text is the verbatim narration, joined by single
    # spaces. A stray double space / newline in narration would break that guarantee.
    for b in beats:
        n = b.get("narration", "")
        if not is_todo(n) and ("\n" in n or "  " in n):
            warns.append(f"beat '{b.get('id')}': narration has a newline/double-space — normalize (storyboard tiles on single spaces).")

    return fails, warns


def main() -> int:
    ap = argparse.ArgumentParser(description="Validate onboarding episode beat sheets.")
    ap.add_argument("episodes", nargs="+", help="episode.json file(s) or a directory")
    args = ap.parse_args()

    files: list[Path] = []
    for p in args.episodes:
        path = Path(p)
        if path.is_dir():
            files.extend(sorted(path.glob("*.episode.json")))
        else:
            files.append(path)
    if not files:
        print("ERROR: no episode.json inputs", file=sys.stderr)
        return 1

    total_fails = 0
    for f in files:
        fails, warns = check_episode(f)
        print(f"\n{f.name}")
        print("-" * 60)
        for x in fails:
            print(f"FAIL  {x}")
        for w in warns:
            print(f"WARN  {w}")
        if not fails and not warns:
            print("PASS  ready to render.")
        elif not fails:
            print(f"PASS  (with {len(warns)} warning(s) to review).")
        else:
            print(f"FAILED  {len(fails)} hard rule(s), {len(warns)} warning(s).")
        total_fails += len(fails)

    print("\n" + "=" * 60)
    print(f"{'FAILED' if total_fails else 'PASS'}  {len(files)} file(s), {total_fails} hard failure(s) total.")
    return 1 if total_fails else 0


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall