Skip to content

opensite-ai/opensite-skills / book-recorded-sessions

book-recorded-sessions

Verified

Plan, record, and merge recorded sessions into book chapters: solo lessons, interviews with a proxy reader, multi-guest panels, or hybrid lesson-plus-conversation episodes that also serve video and short-form clips. Covers contract-driven run-of-show, contributor releases and employer clearance, per-speaker capture and transcripts, speaker-attributed atoms, merging many sessions into a traceable chapter, and clip hand-off flags. Use when chapters are built from spoken recordings or podcasts. Not for narrating the finished audiobook or editing clips.

FileKindSize
SKILL.mdskill md4.9 KB
assets/segment_types.yamlconfig5.1 KB
references/contributor-release.mdmarkdown2.8 KB
references/merge-rules.mdmarkdown2.4 KB
references/session-formats.mdmarkdown3.8 KB
scripts/chapter_trace.pyexecutablescript8.1 KB
scripts/session_ingest.pyexecutablescript9.4 KB
scripts/session_plan.pyexecutablescript8.1 KB

scripts/chapter_trace.py

View on GitHub
#!/usr/bin/env python3
"""Check that merged chapters trace to recorded words and that guests' words are cleared and credited.

Each paragraph of a chapter built from sessions carries one or more source markers,
<!-- src:A-0012 --> or <!-- src:A-0012,A-0031 -->, naming atoms in 01-evidence/ATOMS.csv.
Atoms carry a speaker (contributor_id in CONTRIBUTORS.csv; empty means the author). Text the
agent had to compose sits inside {{ai}} ... {{/ai}} for the author to rewrite (mode T).

Checks, by authorship mode (04-rights/AUTHORSHIP_MODE.md):
  all modes  every src atom exists; no private atoms; each guest used has a contributor
             release row in RIGHTS_LEDGER.csv (status cleared at --lock); a guest with an
             attribution is named in the paragraph that uses their words
  mode T     every paragraph is traced or inside an {{ai}} span; the author's share of the
             chapter's traced words is at least --min-author-share (default 0.6); at --lock
             no {{ai}} words remain
  mode H/G   tracing is optional; guest checks still apply to traced paragraphs

Usage:
  python scripts/chapter_trace.py <project_root> [chapter.md ...] [--lock]
         [--min-author-share 0.6] [--json 06-production/reports/chapter_trace.json]
Default chapters: 03-manuscript/chapters/*.md. Exit 0 when every check passes.
"""
import argparse
import csv
import json
import pathlib
import re
import sys

SRC = re.compile(r"<!--\s*src:([^>]*?)-->")
COMMENT = re.compile(r"<!--.*?-->", re.S)
AI = re.compile(r"\{\{ai\}\}(.*?)\{\{/ai\}\}", re.S)
WORD = re.compile(r"[\w'’-]+")
SKIP = re.compile(r"^\s*(#|!\[|---\s*$|\*\*\*\s*$)")


def rows(path):
    if not path.exists():
        return []
    with open(path, newline="", encoding="utf-8") as fh:
        return list(csv.DictReader(fh))


def words(text):
    return len(WORD.findall(COMMENT.sub(" ", text)))


def mode_of(root):
    p = root / "04-rights" / "AUTHORSHIP_MODE.md"
    m = re.search(r"Selected mode:\s*\**\s*([HTG])\b", p.read_text(encoding="utf-8")) if p.exists() else None
    return m.group(1) if m else None


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("root")
    ap.add_argument("chapters", nargs="*")
    ap.add_argument("--lock", action="store_true")
    ap.add_argument("--min-author-share", type=float, default=0.6)
    ap.add_argument("--json")
    args = ap.parse_args()
    root = pathlib.Path(args.root).resolve()
    files = [pathlib.Path(c) for c in args.chapters] or sorted((root / "03-manuscript" / "chapters").glob("*.md"))
    mode = mode_of(root)
    problems, warnings = [], []
    if mode is None:
        problems.append("authorship mode not selected in 04-rights/AUTHORSHIP_MODE.md")

    atoms = {r["atom_id"].strip(): r for r in rows(root / "01-evidence" / "ATOMS.csv") if (r.get("atom_id") or "").strip()}
    people = {r["contributor_id"].strip(): r for r in rows(root / "01-evidence" / "CONTRIBUTORS.csv")
              if (r.get("contributor_id") or "").strip()}
    authors = [cid for cid, r in people.items() if (r.get("role") or "").strip() == "author"] or ["author"]
    rights = {r.get("item_id", "").strip(): r for r in rows(root / "04-rights" / "RIGHTS_LEDGER.csv")}

    report_chapters = []
    for f in files:
        text = re.sub(r"```.*?```", "\n", f.read_text(encoding="utf-8"), flags=re.S)  # code is not prose
        blocks = []
        for blk in re.split(r"\n\s*\n", text):
            kept = "\n".join(line for line in blk.splitlines() if not SKIP.match(line))  # drop headings, images, rules
            if COMMENT.sub("", kept).strip():
                blocks.append(kept)
        by_speaker, untraced, ai_words, traced_words = {}, [], 0, 0
        for i, blk in enumerate(blocks, 1):
            spans = AI.findall(blk)
            a_w = sum(words(s) for s in spans)
            ai_words += a_w
            body = AI.sub(" ", blk)
            b_w = words(body)
            ids = [x.strip() for m in SRC.findall(blk) for x in re.split(r"[;,]", m) if x.strip()]
            if not ids:
                if b_w:
                    untraced.append(i)
                continue
            speakers = []
            for aid in ids:
                a = atoms.get(aid)
                if a is None:
                    problems.append(f"{f.name} paragraph {i}: src atom {aid} not in ATOMS.csv")
                    continue
                if (a.get("sensitivity") or "").strip() == "private":
                    problems.append(f"{f.name} paragraph {i}: atom {aid} is private")
                elif (a.get("sensitivity") or "").strip() == "sanitize":
                    warnings.append(f"{f.name} paragraph {i}: atom {aid} must be sanitized; confirm before lock")
                sp = (a.get("speaker") or "").strip() or authors[0]
                speakers.append(sp)
                if sp in authors:
                    continue
                person = people.get(sp)
                if person is None:
                    problems.append(f"{f.name} paragraph {i}: atom {aid} speaker {sp!r} not in CONTRIBUTORS.csv")
                    continue
                rid = (person.get("rights_id") or "").strip()
                status = rights.get(rid, {}).get("status", "").strip() if rid in rights else None
                if status is None:
                    problems.append(f"{f.name} paragraph {i}: {sp} has no contributor release in RIGHTS_LEDGER.csv")
                elif status != "cleared":
                    (problems if args.lock else warnings).append(
                        f"{f.name} paragraph {i}: {sp} release {rid} is {status or 'empty'}, not cleared")
                attribution = (person.get("attribution") or "").strip().lower()
                if attribution not in ("", "none", "uncredited"):
                    name = (person.get("name") or "").strip()
                    first = name.split()[0] if name else ""
                    plain = COMMENT.sub(" ", body).lower()
                    if not ((name and name.lower() in plain) or (first and re.search(rf"\b{re.escape(first.lower())}\b", plain))):
                        problems.append(f"{f.name} paragraph {i}: uses {sp}'s words without naming them")
            if speakers and b_w:
                traced_words += b_w
                for sp in speakers:
                    by_speaker[sp] = by_speaker.get(sp, 0) + b_w / len(speakers)
        author_w = sum(v for k, v in by_speaker.items() if k in authors)
        share = round(author_w / traced_words, 3) if traced_words else None
        if mode == "T":
            if untraced:
                problems.append(f"{f.name}: paragraphs {untraced} have no src marker and are not marked {{{{ai}}}}")
            if share is not None and share < args.min_author_share:
                problems.append(f"{f.name}: author share of traced words {share:.0%} is below {args.min_author_share:.0%}")
            if args.lock and ai_words:
                problems.append(f"{f.name}: {ai_words} words still inside {{{{ai}}}} spans at lock")
        report_chapters.append({"file": f.name, "paragraphs": len(blocks), "untraced_paragraphs": untraced,
                                "traced_words": traced_words, "ai_words": ai_words, "author_share": share,
                                "words_by_speaker": {k: round(v) for k, v in by_speaker.items()}})
    if not files:
        problems.append("no chapter files found")

    report = {"pass": not problems, "mode": mode, "lock": args.lock, "min_author_share": args.min_author_share,
              "chapters": report_chapters, "problems": problems, "warnings": warnings}
    for c in report_chapters:
        sh = "n/a" if c["author_share"] is None else f"{c['author_share']:.0%}"
        print(f"{c['file']}: {c['paragraphs']} paragraphs, untraced {len(c['untraced_paragraphs'])}, "
              f"author share {sh}, ai words {c['ai_words']}")
    for p in problems:
        print(f"  - {p}")
    for w_ in warnings:
        print(f"  ~ {w_}")
    print("PASS" if report["pass"] else "FAIL")
    if args.json:
        pathlib.Path(args.json).write_text(json.dumps(report, indent=2), encoding="utf-8")
    return 0 if report["pass"] else 1


if __name__ == "__main__":
    sys.exit(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