{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-video-evidence-process",
  "slug": "video-evidence-process",
  "title": "Repeatable video evidence processing",
  "summary": "Evidence-preserving video follow-up workflow covering long and short recordings, project setup, segmentation, chat carry-forward, Oracle/Gemini analysis and recovery, prompt templates, verification, keyframes, Git practices, publication review, and planned…",
  "category": "Context",
  "tags": [
    "video",
    "evidence",
    "quality"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Project Structure",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Run Config",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Mode Matrix",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Decision Tree",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Project Setup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Long Recording Workflow",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Short Recording Workflow",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Gemini Readiness And Failure Recovery",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Gemini Browser Cleanup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Gemini Chunk Analysis",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Omissions Pass",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Local Reconciliation",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Short Clip Analysis",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Final Packet Generation",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Oracle Review",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Verification Gates",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Keyframes",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Git Workflow",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Oracle Session Receipts",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Final Packet Review",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/End-To-End Checklist",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Later Automation",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "context",
  "wordCount": 4269,
  "url": "/topics/codex-video-evidence-process/",
  "markdownUrl": "/markdown/codex-video-evidence-process.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-video-evidence-process.json",
  "headings": [
    {
      "id": "project-structure",
      "text": "Project Structure",
      "level": 2
    },
    {
      "id": "run-config",
      "text": "Run Config",
      "level": 2
    },
    {
      "id": "mode-matrix",
      "text": "Mode Matrix",
      "level": 2
    },
    {
      "id": "decision-tree",
      "text": "Decision Tree",
      "level": 2
    },
    {
      "id": "project-setup",
      "text": "Project Setup",
      "level": 2
    },
    {
      "id": "long-recording-workflow",
      "text": "Long Recording Workflow",
      "level": 2
    },
    {
      "id": "short-recording-workflow",
      "text": "Short Recording Workflow",
      "level": 2
    },
    {
      "id": "gemini-readiness-and-failure-recovery",
      "text": "Gemini Readiness And Failure Recovery",
      "level": 2
    },
    {
      "id": "gemini-browser-cleanup",
      "text": "Gemini Browser Cleanup",
      "level": 2
    },
    {
      "id": "prompt-templates",
      "text": "Prompt Templates",
      "level": 2
    },
    {
      "id": "gemini-chunk-analysis",
      "text": "Gemini Chunk Analysis",
      "level": 3
    },
    {
      "id": "omissions-pass",
      "text": "Omissions Pass",
      "level": 3
    },
    {
      "id": "local-reconciliation",
      "text": "Local Reconciliation",
      "level": 3
    },
    {
      "id": "short-clip-analysis",
      "text": "Short Clip Analysis",
      "level": 3
    },
    {
      "id": "final-packet-generation",
      "text": "Final Packet Generation",
      "level": 3
    },
    {
      "id": "oracle-review",
      "text": "Oracle Review",
      "level": 3
    },
    {
      "id": "verification-gates",
      "text": "Verification Gates",
      "level": 2
    },
    {
      "id": "keyframes",
      "text": "Keyframes",
      "level": 2
    },
    {
      "id": "git-workflow",
      "text": "Git Workflow",
      "level": 2
    },
    {
      "id": "oracle-session-receipts",
      "text": "Oracle Session Receipts",
      "level": 2
    },
    {
      "id": "final-packet-review",
      "text": "Final Packet Review",
      "level": 2
    },
    {
      "id": "end-to-end-checklist",
      "text": "End-To-End Checklist",
      "level": 2
    },
    {
      "id": "automation-responsibilities",
      "text": "Automation Responsibilities",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Repeatable video evidence processing\n\nStatus: implementation-ready process spec\nOwner: local coding agent\nReference run: `workshop-followup/`\nPrimary output: verified follow-up materials from one or more source videos\n\nThis process turns a raw workshop recording, tutorial, app walkthrough, bug reproduction, or short screen recording into a reviewable artifact project. It is built from the completed `workshop-followup/` run and the Oracle review session `video-pipeline-repeatable-process`.\n\nThe pipeline has two main paths:\n\n1. Long workshop path: segment long recordings, remove verified breaks, carry forward break chat, analyze chunks, verify omissions, extract keyframes, reconcile, and assemble a teammate packet.\n2. Short recording path: skip segmentation unless needed, analyze the clip directly, optionally extract keyframes, verify outputs, and produce a compact follow-up note, bug packet, design brief, or requirements document.\n\nThe core rule is evidence preservation. Keep the original media immutable, preserve original timestamps when a source timeline exists, save model prompts/results/logs, and keep verification receipts next to every generated claim.\n\nFor this browser-based workflow, Gemini video analysis uses\nOracle browser mode and must clean up after itself. After a chunk's analysis is saved\nand verified, close the Gemini tab opened for that chunk. Leave the browser/profile\nalive for reuse, but do not leave accumulated `gemini.google.com/app` tabs on the\nremote Mac mini.\n\n## Project Structure\n\nUse one run folder per video or video set:\n\n```text\nruns/\n  YYYY-MM-DD-slug/\n    README.md\n    run-config.json\n    inputs/\n      source-video.mp4\n      source-video.sha256\n      transcript.vtt\n      transcript.md\n      chat.txt\n      chat.md\n      screenshots/\n      clips/\n    receipts/\n      ffprobe.source.json\n      media-info.md\n      source-file-list.txt\n      tool-versions.txt\n      git-status.before.txt\n      git-status.after.txt\n    analysis/\n      timeline-initial.json\n      silencedetect.log\n      boundary-candidates.md\n      segmentation-notes.md\n      source-timeline.md\n    segments/\n      segment-manifest.v1.json\n      segment-manifest.v1.md\n      segment-manifest.v2.json\n      segment-manifest.v2.md\n    break-chat/\n      morning-break.chat.md\n      lunch-break.chat.md\n      other-break.chat.md\n    chunks/\n      video-manifest.json\n      01/\n        chunk.mp4\n        chunk.ffprobe.json\n        transcript.md\n        chat.md\n        carry-forward-chat.md\n        next-chunk-preview.md\n        gemini-prompt.md\n        expected-sentinel.txt\n        gemini-run.log\n        gemini-result.json\n        gemini-analysis.md\n        gemini-analysis.extracted.json\n        gemini-omissions-prompt.md\n        gemini-omissions-run.log\n        gemini-omissions-result.json\n        gemini-omissions.md\n        final-reconciled.md\n        final-reconciled.json\n        keyframes/\n          candidates.json\n          extracted/\n          strips/\n          contact-sheet.jpg\n          review.md\n        verification/\n          expected-items.json\n          extracted-items.json\n          coverage-report.md\n          hallucination-report.md\n          timestamp-report.md\n          qa-report.md\n          visual-claim-report.md\n    oracle/\n      planning.md\n      review.md\n      sessions/\n    final/\n      README.md\n      teammate-followup-guide.md\n      chapter-index.md\n      resources-and-links.md\n      qa-index.md\n      exercises.md\n      keyframes-manifest.md\n      keyframes-manifest.json\n      instructor-review-checklist.md\n    publication/\n      public-draft/\n      private-redactions.md\n      publish-checklist.md\n```\n\nThe current reference artifacts live in `workshop-followup/`. New runs should use `runs/<date>-<slug>/` so the reference run remains untouched.\n\n## Run Config\n\nCreate `run-config.json` before processing:\n\n```json\n{\n  \"run_id\": \"example-workshop\",\n  \"title\": \"Example Workshop\",\n  \"mode\": \"long_workshop\",\n  \"source\": {\n    \"video\": \"inputs/source-video.mp4\",\n    \"transcript\": \"inputs/transcript.vtt\",\n    \"chat\": \"inputs/chat.txt\",\n    \"screenshots\": \"inputs/screenshots\",\n    \"clips\": \"inputs/clips\"\n  },\n  \"policy\": {\n    \"preserve_original_timestamps\": true,\n    \"chunk_target_minutes\": \"semantic-under-30\",\n    \"chunk_max_minutes\": 30,\n    \"dead_space_removal\": \"only verified long silence plus transcript/chat break evidence\",\n    \"default_video_overlap_seconds\": 0,\n    \"semantic_boundary_overlap_seconds\": 5,\n    \"qa_boundary_overlap_seconds\": 15,\n    \"chat_carry_forward\": true,\n    \"dedupe_final_materials\": true,\n    \"large_binary_git_policy\": \"local-only-unless-explicitly-approved\"\n  },\n  \"outputs\": {\n    \"student_packet\": true,\n    \"keyframes\": true,\n    \"contact_sheets\": true,\n    \"verification_reports\": true\n  }\n}\n```\n\n## Mode Matrix\n\n| Mode | Typical input | Segmentation | Transcript/chat | Keyframes | Gemini video pass | Output |\n|---|---|---:|---:|---:|---:|---|\n| Long workshop | 2-8 hour Zoom/workshop recording | Required | Required if available | Required | Required | Full teammate packet |\n| Medium tutorial | 20-60 minute lesson | Optional semantic chunks | Transcript required, chat optional | Recommended | Required when deriving facts from video | Guide, chapter index, resources |\n| Short bug reproduction | 30 sec-8 min screen recording | Skip | Optional | Required | Required for observed behavior | Bug report, repro steps, implementation brief |\n| Quick design feedback | 1-12 min screen and voice | Skip | Recommended if voiceover matters | Required | Required for visual/audio claims | Design-change brief, QA checklist |\n| Raw app walkthrough | 5-30 min app demo | Skip under 12 min; segment over 20 min | Recommended | Required | Required for requirements/QA extraction | Requirements doc, acceptance criteria |\n\n\"Optional\" applies only to extra Oracle planning/review over text artifacts. It does\nnot mean the video-watching step can be skipped when the deliverable depends on what\nis visible or audible in the recording.\n\n## Decision Tree\n\nSegment when any of these are true:\n\n- Video duration is over 30 minutes.\n- There are real breaks, lunch, pre-roll, or dead air.\n- Q&A spans topic transitions.\n- Chat must be aligned to the video.\n- The target output is a course packet, teammate packet, chapter index, or publication bundle.\n\nSkip segmentation when all of these are true:\n\n- Video duration is 12 minutes or less.\n- There is no long dead air or break.\n- Chat is absent, irrelevant, or small enough to include directly.\n- One model pass can analyze the whole video reliably.\n- The target output is a short note, bug report, design feedback memo, or compact implementation plan.\n\nUse a medium path when the video is 12-45 minutes, has no real breaks, and has 2-4 obvious sections. In that case, keep one physical video and create timestamped sections unless model upload/runtime gets awkward.\n\nRemove a video span only when long silence or inactive-screen evidence, transcript evidence, and chat evidence agree that the span is a break or dead space. Never discard chat from a removed span. Save it in `break-chat/` and carry it forward to the next spoken chunk when it contains a question, answer, link, or context used later.\n\nExtract keyframes when screen share, terminal commands, browser pages, demos, design feedback, or visual claims appear. Skip keyframes only for pure audio/talking-head content where visual evidence cannot change the output.\n\nRun an omissions pass when coverage is incomplete, missing URLs exist, missing chat questions exist, keyframe candidates are thin, machine JSON is missing/unparseable, timestamps are out of range, or hallucination checks find invented tools/links/commands.\n\n## Project Setup\n\n```bash\ncd /path/to/workshop-video-followup-pipeline\nRUN_ID=\"$(date +%Y-%m-%d)-example-workshop\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,segments,break-chat,chunks,oracle/sessions,final,publication}\ngit status --short > \"$RUN_DIR/receipts/git-status.before.txt\"\n```\n\nRecord tool versions:\n\n```bash\n{\n  echo \"# Tool Versions\"\n  echo\n  echo \"date: $(date -u +%Y-%m-%dT%H:%M:%SZ)\"\n  echo\n  echo \"## ffmpeg\"\n  ffmpeg -version | head -n 3 || true\n  echo\n  echo \"## ffprobe\"\n  ffprobe -version | head -n 3 || true\n  echo\n  echo \"## git\"\n  git --version || true\n  echo\n  echo \"## jq\"\n  jq --version || true\n  echo\n  echo \"## python\"\n  python3 --version || true\n} > \"$RUN_DIR/receipts/tool-versions.txt\"\n```\n\nCopy inputs. Do not mutate originals:\n\n```bash\ncp \"/absolute/path/to/source-video.mp4\" \"$RUN_DIR/inputs/source-video.mp4\"\n\n# Optional\ncp \"/absolute/path/to/transcript.vtt\" \"$RUN_DIR/inputs/transcript.vtt\"\ncp \"/absolute/path/to/chat.txt\" \"$RUN_DIR/inputs/chat.txt\"\n```\n\nHash source assets and save file list:\n\n```bash\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" > \"$RUN_DIR/inputs/source-video.sha256\"\nfind \"$RUN_DIR/inputs\" -maxdepth 2 -type f -print0 \\\n  | xargs -0 shasum -a 256 \\\n  > \"$RUN_DIR/receipts/source-file-list.txt\"\n```\n\nProbe the source video:\n\n```bash\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nCreate a human-readable media receipt:\n\n```bash\n{\n  echo \"# Media Info\"\n  echo\n  echo \"source: $RUN_DIR/inputs/source-video.mp4\"\n  echo \"sha256: $(cut -d ' ' -f1 \"$RUN_DIR/inputs/source-video.sha256\")\"\n  echo\n  jq -r '.format | \"- duration: \\(.duration)\\n- size: \\(.size)\\n- bit_rate: \\(.bit_rate)\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n  echo\n  echo \"## Streams\"\n  jq -r '.streams[] | \"- index=\\(.index) type=\\(.codec_type) codec=\\(.codec_name) duration=\\(.duration // \"unknown\") width=\\(.width // \"-\") height=\\(.height // \"-\")\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n} > \"$RUN_DIR/receipts/media-info.md\"\n```\n\nCommit the initial evidence:\n\n```bash\ngit add \"$RUN_DIR/run-config.json\" \"$RUN_DIR/inputs\" \"$RUN_DIR/receipts\"\ngit commit -m \"Capture source evidence for $RUN_ID\"\n```\n\n## Long Recording Workflow\n\n1. Detect silence:\n\n```bash\nffmpeg -hide_banner -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -af silencedetect=noise=-35dB:d=5 \\\n  -f null - 2> \"$RUN_DIR/analysis/silencedetect-35db-5s.log\"\n```\n\n2. Draft `analysis/boundary-candidates.md` from silence, transcript, and chat evidence.\n\n3. Create `segments/segment-manifest.v1.json` and `.md`. Preserve original timestamps. Use semantic chunks under 30 minutes. Remove break spans only when evidence supports removal.\n\n4. Run `$oracle-packx` before finalizing segmentation when the run is long, public, or ambiguous. Bundle only text artifacts:\n\n```bash\nmkdir -p ~/.oracle/bundles\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --preview --no-interactive\n\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --limit 900k -f markdown --no-interactive --stdout --strip-comments --minify \\\n  > ~/.oracle/bundles/video-followup-segmentation-review.txt\n\ntest -s ~/.oracle/bundles/video-followup-segmentation-review.txt\n```\n\nAsk Oracle in browser mode only. If using the skill, invoke `$oracle-packx`; if using the CLI fallback, keep browser mode explicit:\n\n```bash\noracle --engine browser \\\n  --model gpt-5.5-pro \\\n  --browser-thinking-time extended \\\n  --slug video-followup-segmentation-review \\\n  --file ~/.oracle/bundles/video-followup-segmentation-review.txt \\\n  -p \"$(cat \"$RUN_DIR/oracle/planning.md\")\"\n```\n\nSave the Oracle conversation URL, local bundle path, prompt, and `~/.oracle/sessions/<slug>/output.log` reference in `oracle/sessions/<slug>.md`.\n\n5. Revise into `segments/segment-manifest.v2.json` and `.md`.\n\n6. Cut chunks from the original source:\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01\"\nffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -map 0 -c copy \\\n  \"$RUN_DIR/chunks/01/chunk.mp4\"\n\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/chunks/01/chunk.mp4\" \\\n  > \"$RUN_DIR/chunks/01/chunk.ffprobe.json\"\n```\n\nUse `-c copy` for fast archival cuts when keyframe accuracy is acceptable. Use re-encode for frame-exact cuts:\n\n```bash\nffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -map 0 -c:v libx264 -crf 18 -preset veryfast -c:a aac \\\n  \"$RUN_DIR/chunks/01/chunk.frame-exact.mp4\"\n```\n\n7. Slice transcript and chat into `chunks/<nn>/transcript.md`, `chat.md`, and `carry-forward-chat.md`.\n\n8. Create `chunks/video-manifest.json` with chunk id, original range, file path, transcript path, chat path, carry-forward path, ffprobe path, and verification status.\n\n## Short Recording Workflow\n\nUse this path for quick screen captures, short bug reproductions, design notes, and small app walkthroughs.\n\n```bash\nRUN_ID=\"$(date +%Y-%m-%d)-quick-clip\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,chunks/01,final}\ncp \"/absolute/path/to/clip.mov\" \"$RUN_DIR/inputs/source-video.mov\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mov\" > \"$RUN_DIR/inputs/source-video.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mov\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor short clips, do not cut video by default. Symlink or copy it as the single chunk:\n\n```bash\nln -s ../../inputs/source-video.mov \"$RUN_DIR/chunks/01/chunk.mov\"\n```\n\nCreate `chunks/01/gemini-prompt.md` using the short clip prompt in this doc, attach the clip directly to Gemini/video model, and save:\n\n```text\nchunks/01/expected-sentinel.txt\nchunks/01/gemini-run.log\nchunks/01/gemini-result.json\nchunks/01/gemini-analysis.md\nchunks/01/final-reconciled.md\nfinal/README.md\n```\n\nFinal output by short mode:\n\n- Bug reproduction: `final/bug-report.md`, `final/repro-steps.md`, `final/acceptance-checks.md`\n- Design feedback: `final/design-brief.md`, `final/visual-acceptance-criteria.md`\n- App walkthrough: `final/requirements.md`, `final/qa-checklist.md`\n- Tiny tutorial: `final/summary.md`, `final/resources-and-links.md`\n\nRun the same malformed URL and hallucination checks even for short clips.\n\nFor YouTube research batches, add these source-selection rules before downloading:\n\n- Search broadly, but select by actual YouTube metadata (`upload_date`), not title text.\n- Enforce user cutoffs exactly. Example: after a chosen cutoff means\n  `upload_date >= CUTOFF_YYYYMMDD`.\n- Exclude topic collisions, coupon/affiliate uploads, auto-generated music/topic\n  uploads, and unrelated videos.\n- Save selected videos in `queue.json` with `id`, `title`, `uploader`,\n  `upload_date`, `duration`, and `url`.\n- Use Chrome cookies with `yt-dlp` when YouTube challenges require it.\n- Space Gemini upload starts by about five minutes for batch runs only after the first\n  attached-video probe passes and no unresolved run is pending, unless the user asks\n  for a different cadence.\n\nFor each batch item, use a topic-specific prompt. Do not copy old prompt text from a\ndifferent topic without replacing the product/domain language.\n\n## Gemini Readiness And Failure Recovery\n\nBefore a large batch, run one tiny attached-video Gemini probe. Do not rely on a\ntext-only Gemini probe as the sole readiness check because text-only runs may use a\ndifferent HTTP/cookie path than attached-video DOM upload.\n\nRequired preflight receipts:\n\n- configured browser mode and Gemini provider routing;\n- visible signed-in Gemini UI, or a completed attached-video probe;\n- prompt path and exact expected sentinel;\n- run/session metadata;\n- attachment upload completion;\n- final response or recovered visible response with sentinel;\n- completed tab cleanup.\n\nOn any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit,\nor upload warning, stop new batch starts. Inspect the active Gemini tab, classify the\nstate, and retry only the affected chunk if no valid sentinel response exists.\n\nWrite the exact expected sentinel into `chunks/<nn>/expected-sentinel.txt` before each\nGemini run. Verification and recovery should compare against that file, not infer the\nsentinel shape from memory.\n\n## Gemini Browser Cleanup\n\nWhen using Oracle CLI fallback with `--browser-keep-browser`, cleanup is mandatory:\n\n1. Wait for the run to finish.\n2. Save every needed extraction artifact from the Gemini response:\n   `gemini-result.json`, `gemini-analysis.md`, `gemini-analysis.extracted.json` when\n   expected, machine JSON, and any recovery note if the response was recovered by tab\n   inspection.\n3. Verify the analysis is non-empty and contains the expected\n   `END_OF_VIDEO_ANALYSIS ...` sentinel.\n4. Close only the completed and fully extracted Gemini tab for that run.\n5. Do not close tabs for active uploads, still-generating sessions, unresolved wrapper\n   errors, or completed-looking tabs whose visible response has not been extracted.\n6. Do not kill Chrome; Oracle needs the signed-in profile for future runs.\n\nFor scripted runs, implement cleanup as a post-extraction step, not as a generic\n`finally` block. A safe script order is: save wrapper result, inspect/recover tab output\nif needed, write extracted JSON, verify the exact expected sentinel, then close the\nspecific Gemini tab target. If any extraction or sentinel check fails, leave the tab\nopen and record the Chrome port/target for recovery.\n\nIf exact target close tooling is available, use Chrome DevTools Protocol to close the\nspecific `gemini.google.com/app` target created for the run. If not, list tabs first,\nidentify completed or empty Gemini tabs, and close only those. Avoid broad \"close all\nGemini\" actions while a batch is running.\n\nWhen classifying stale tabs:\n\n- Empty generic Gemini tabs from failed diagnostics may be closed after inspection.\n- Active upload/generation tabs must stay open.\n- Tabs with conversation state or auto-generated titles must be checked for saved\n  output and the expected sentinel before closing.\n- Never use broad \"close all Gemini tabs\" while a batch is active.\n\n## Prompt Templates\n\n### Gemini Chunk Analysis\n\n```markdown\nYou are analyzing one source-preserving video chunk for a follow-up packet.\n\nRun metadata:\n- run_key: {{run_key}}\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- chunk_video: {{chunk_video_path}}\n- transcript: included below\n- chat: included below\n- carry_forward_chat: included below\n- next_chunk_preview: included below\n\nHard rules:\n1. Preserve original recording timestamps.\n2. Separate transcript evidence, chat evidence, visual evidence, and inference.\n3. Do not invent tools, commands, URLs, files, speakers, or UI labels.\n4. Include unanswered and deferred questions.\n5. Flag every policy-sensitive area, especially browser automation, cookies, quota/rate limits, private accounts, and publishing.\n6. Return both Markdown and fenced JSON.\n7. End with: END_OF_VIDEO_ANALYSIS {{run_key}} {{chunk_id}}\n\nReturn:\n# Chunk Analysis: {{chunk_id}}\n## 1. Overview\n## 2. Dense Timeline\n## 3. Concept Inventory\n## 4. Demo / Screen Activity\n## 5. Questions And Answers\n## 6. Links / Tools / Commands / References\n## 7. Keyframes To Capture\n## 8. teammate Exercises\n## 9. Uncertainties / Needs Review\n## 10. Machine JSON\n```\n\n### Omissions Pass\n\n```markdown\nYou are auditing a prior video analysis for omissions.\n\nInputs:\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- coverage_report: {{coverage_report}}\n- expected_items: {{expected_items_json}}\n- prior_analysis: {{prior_analysis}}\n\nFind only omissions and corrections. Do not repeat complete items.\n\nRequired focus:\n1. Missing URLs exactly as they appeared.\n2. Missing chat questions, including unanswered/deferred questions.\n3. Missing demo steps.\n4. Missing keyframe candidates.\n5. Unsupported visual claims.\n6. Hallucinated tools, commands, links, or files.\n7. Parseable fenced JSON.\n\nReturn:\n# Omissions And Corrections: {{chunk_id}}\n## Additions\n## Corrections\n## Remove Or Downgrade\n## Remaining Human Review\n## Machine JSON\n```\n\n### Local Reconciliation\n\n```markdown\nReconcile one analyzed chunk into an evidence-grounded final chunk record.\n\nInputs:\n- segment manifest entry\n- transcript slice\n- chat slice\n- carry-forward chat\n- main analysis\n- omissions analysis\n- verification reports\n- keyframe review\n\nRules:\n1. Preserve original timestamps.\n2. Remove malformed URLs.\n3. Do not include any URL/tool/command unless supported by transcript, chat, carry-forward chat, local path, or keyframe review.\n4. Do not claim a visual is visible unless keyframe review confirms it.\n5. Preserve unanswered/deferred questions.\n6. Preserve editorial warnings.\n7. Deduplicate overlap by normalized timestamp + item type + text hash.\n\nReturn Markdown and JSON with:\n- status: PASS | PASS_WITH_WARNINGS | FAIL\n- counts\n- timeline summary\n- concepts\n- Q&A\n- links/tools/commands\n- demos\n- keyframes\n- warnings\n- teammate-material candidates\n```\n\n### Short Clip Analysis\n\n```markdown\nYou are analyzing a short screen recording or app walkthrough.\n\nSource:\n- run_key: {{run_key}}\n- recording_type: short_clip | bug_reproduction | design_feedback | app_walkthrough\n- original_recording_range: 00:00:00 -> {{duration}}\n- source_video_sha256: {{source_video_sha256}}\n\nHard rules:\n1. Use timestamps relative to the clip unless an original recording timeline is provided.\n2. Do not invent commands, files, UI labels, URLs, or implementation details.\n3. Separate observed behavior from inferred intent.\n4. Include timestamped screenshot/keyframe candidates for visual claims.\n5. For a bug reproduction, produce repro steps and expected vs actual behavior.\n6. For design feedback, produce requested changes and visual acceptance criteria.\n7. For an app walkthrough, produce requirements and QA checks.\n8. Include uncertainties and manual review points.\n\nReturn:\n# Short Video Analysis: {{run_key}}\n## 1. Summary\n## 2. Observed Timeline\n## 3. User Intent / Requirements\n## 4. Reproduction Steps Or Walkthrough Steps\n## 5. Expected Vs Actual Behavior\n## 6. Implementation Notes\n## 7. QA / Acceptance Criteria\n## 8. Keyframes To Extract\n## 9. Risks / Unknowns\n## 10. Machine JSON\n```\n\n### Final Packet Generation\n\n```markdown\nAssemble a teammate follow-up packet from verified chunk records.\n\nInputs:\n- segments/segment-manifest.v2.md\n- chunks/*/final-reconciled.md\n- chunks/*/final-reconciled.json\n- chunks/*/verification/*.md\n- final/keyframes-manifest.json if present\n- resources extracted from chat/transcript\n\nRules:\n1. Use original recording timestamps.\n2. Do not include unverified visual claims.\n3. Do not include malformed URLs.\n4. Do not present experimental tools as official recommendations unless approved.\n5. Keep policy-sensitive automation/cookie/quota/rate-limit sections as editorial notes.\n6. Distinguish publication-ready files from reference drafts.\n7. Deduplicate overlap and carry-forward repeated material.\n\nCreate:\n- final/README.md\n- final/teammate-followup-guide.md\n- final/chapter-index.md\n- final/resources-and-links.md\n- final/qa-index.md\n- final/exercises.md\n- final/keyframes-manifest.md\n- final/keyframes-manifest.json\n- final/instructor-review-checklist.md\n```\n\n### Oracle Review\n\n```markdown\n[{{slug}}]\n\nProject briefing:\n{{project_briefing}}\n\nGoal:\n{{goal}}\n\nPrior-State Ledger:\n- prior_oracle_session: {{prior_oracle_session_or_none}}\n- last_oracle_recommendation: {{summary_or_none}}\n- implemented_since_prior_oracle: {{files_or_none}}\n- verified_since_prior_oracle: {{commands_or_none}}\n- failed_proof_or_blocker: {{receipt_or_none}}\n- narrowing_decision: {{one_slice}}\n- files_functions_now_in_scope: {{paths}}\n- files_functions_out_of_scope: {{paths}}\n- next_falsifiable_verification: {{command_or_receipt}}\n- forward_progress_index: {{score_and_arithmetic}}\n\nDeliverable:\nEvaluate segmentation, chat carry-forward, analysis prompts, verification gates, final packet readiness, privacy/security risks, and the one highest-leverage next local action.\n\nReturn your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools.\n```\n\n## Verification Gates\n\nRun malformed URL checks on every final packet:\n\n```bash\nrg -n 'https://www\\.\\.\\.|https://www\\s|/\"|\\| .*: \\||Context:' \"$RUN_DIR/final\" || true\n```\n\nExtract exact URLs from chat/transcript and compare against final resources:\n\n```bash\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/chunks\" \"$RUN_DIR/break-chat\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.expected-urls.txt\"\n\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/final/resources-and-links.md\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.final-urls.txt\"\n\ncomm -23 \"$RUN_DIR/verification.expected-urls.txt\" \"$RUN_DIR/verification.final-urls.txt\" \\\n  > \"$RUN_DIR/verification.missing-urls.txt\"\n```\n\nValidate timestamps stay within range, except carry-forward chat:\n\n```bash\npython3 scripts/validate-timestamps.py \"$RUN_DIR\" \\\n  > \"$RUN_DIR/receipts/timestamp-validation.log\"\n```\n\nIf the script does not exist yet, perform a manual timestamp pass and save it as `chunks/<nn>/verification/timestamp-report.md`.\n\nCheck machine JSON:\n\n```bash\nfind \"$RUN_DIR/chunks\" -name '*.json' -print0 | xargs -0 -n1 jq empty\n```\n\nRequired chunk gate files:\n\n```text\nchunks/<nn>/verification/coverage-report.md\nchunks/<nn>/verification/hallucination-report.md\nchunks/<nn>/verification/timestamp-report.md\nchunks/<nn>/verification/qa-report.md\nchunks/<nn>/final-reconciled.md\nchunks/<nn>/final-reconciled.json\n```\n\nChunk status meanings:\n\n- `PASS`: complete and publication-safe after ordinary instructor review.\n- `PASS_WITH_WARNINGS`: usable evidence, but warnings must be reviewed before publication.\n- `FAIL`: rerun analysis, omissions, or reconciliation before using the chunk.\n\n## Keyframes\n\nCandidate extraction prompt output should include timestamp, reason, expected visual, priority, and confidence.\n\nExtract deterministic frames:\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01/keyframes/extracted\"\nffmpeg -hide_banner -ss 00:23:48 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -frames:v 1 \\\n  \"$RUN_DIR/chunks/01/keyframes/extracted/00-23-48-automation-verification.jpg\"\n```\n\nCreate contact sheet:\n\n```bash\nfind \"$RUN_DIR/chunks/01/keyframes/extracted\" -name '*.jpg' | sort \\\n  > \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\"\n\nffmpeg -hide_banner -f concat -safe 0 \\\n  -i <(sed \"s#^#file '#; s#$#'#\" \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\") \\\n  -vf \"scale=320:-1,tile=3x4\" \\\n  \"$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg\"\n```\n\nIf process substitution is unavailable, generate the concat list as a real file and pass it to ffmpeg.\n\n## Git Workflow\n\nInitialize a new artifact project:\n\n```bash\nmkdir -p /path/to/new-video-followup-project\ncd /path/to/new-video-followup-project\ngit init\ncat > README.md <<'EOF'\n# Video Follow-Up Pipeline\n\nLocal artifact project for repeatable video follow-up runs.\nEOF\ngit add README.md\ngit commit -m \"Initialize video follow-up project\"\n```\n\nUse proof-oriented commit boundaries:\n\n```bash\ngit commit -m \"Capture source evidence for <run_id>\"\ngit commit -m \"Draft initial segmentation for <run_id>\"\ngit commit -m \"Record Oracle segmentation review for <run_id>\"\ngit commit -m \"Revise semantic chunk manifest\"\ngit commit -m \"Cut video chunks and ffprobe receipts\"\ngit commit -m \"Slice transcript and chat by chunk\"\ngit commit -m \"Run Gemini analysis for chunks 01-03\"\ngit commit -m \"Add verification reports for chunks 01-03\"\ngit commit -m \"Run omissions pass for chunk 01\"\ngit commit -m \"Reconcile verified chunk analyses\"\ngit commit -m \"Extract and review keyframe candidates\"\ngit commit -m \"Assemble teammate follow-up packet\"\ngit commit -m \"Document repeatable video follow-up process\"\n```\n\nDefault binary policy for future runs:\n\n- Commit text artifacts, manifests, prompts, logs, JSON, Markdown, reports, and checksums.\n- Do not commit large raw videos unless explicitly approved.\n- Commit chunk videos only for local archival projects or when Git LFS is configured.\n- Commit keyframes/contact sheets only when they are small enough and useful for review.\n\nSuggested `.gitignore` for future automation projects:\n\n```gitignore\nruns/**/inputs/*.mp4\nruns/**/inputs/*.mov\nruns/**/inputs/*.mkv\nruns/**/chunks/**/*.mp4\nruns/**/chunks/**/*.mov\n\n!runs/**/inputs/*.sha256\n!runs/**/receipts/**\n!runs/**/segments/**\n!runs/**/chunks/**/*.json\n!runs/**/chunks/**/*.md\n!runs/**/chunks/**/*.log\n!runs/**/final/**\n!runs/**/oracle/**\n\nruns/**/chunks/**/keyframes/extracted/*.jpg\nruns/**/chunks/**/keyframes/extracted/*.png\nruns/**/chunks/**/keyframes/strips/*.jpg\nruns/**/chunks/**/keyframes/contact-sheet*.jpg\n```\n\nIf committing binaries intentionally:\n\n```bash\ngit add -f \"$RUN_DIR/chunks/01/chunk.mp4\"\ngit add -f \"$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg\"\n```\n\n## Oracle Session Receipts\n\nFor every `$oracle-packx` call, save:\n\n```text\n- slug\n- date\n- run id\n- browser mode: true\n- ChatGPT conversation URL\n- bundle path\n- bundle sha256\n- prompt path\n- output log path\n- local decisions accepted/rejected\n- commit before\n- commit after\n```\n\nTemplate:\n\n```markdown\n# Oracle Session: {{session_slug}}\n\n- date:\n- local_run:\n- browser_mode: true\n- session_url:\n- bundle_path:\n- bundle_sha256:\n- prompt_file:\n- output_file:\n- commit_before:\n- commit_after:\n\n## Question\n\n## Oracle Response Summary\n\n## Local Decisions\n\nAccepted:\n\nRejected:\n\nFollow-up:\n```\n\n## Final Packet Review\n\nTreat these as first publication candidates:\n\n- `final/README.md`\n- `final/teammate-followup-guide.md`\n- `final/chapter-index.md`\n- `final/resources-and-links.md`\n- `final/instructor-review-checklist.md`\n\nTreat these as reference drafts until edited:\n\n- `final/qa-index.md`\n- `final/exercises.md`\n- `final/keyframes-manifest.md`\n\nManual approval is mandatory for:\n\n- platform automation\n- browser automation\n- cookies\n- session replay\n- quota/rate-limit behavior\n- account credentials\n- private emails\n- private chat exports\n- meeting transcript bot URLs\n- teammate names\n- screenshots of private repos\n- local network addresses\n- QR codes\n- API keys\n- package security claims\n- third-party service recommendations\n- public publishing\n\n## End-To-End Checklist\n\nProject setup:\n\n- [ ] Create run folder.\n- [ ] Copy source video into `inputs/`.\n- [ ] Copy transcript/chat/screenshots/clips if available.\n- [ ] Save source SHA256.\n- [ ] Save ffprobe source receipt.\n- [ ] Save tool versions.\n- [ ] Commit source evidence receipts.\n\nLong recording preprocessing:\n\n- [ ] Run `silencedetect`.\n- [ ] Review transcript and chat around silence spans.\n- [ ] Draft boundary candidates.\n- [ ] Create `segment-manifest.v1.json` and `.md`.\n- [ ] Bundle planning context with `$oracle-packx`.\n- [ ] Run Oracle review in browser mode.\n- [ ] Save Oracle session link/output locally.\n- [ ] Create `segment-manifest.v2.json` and `.md`.\n- [ ] Commit segmentation.\n\nChunk creation:\n\n- [ ] Cut chunks from original video.\n- [ ] `ffprobe` every chunk.\n- [ ] Create `chunks/video-manifest.json`.\n- [ ] Slice transcript per chunk.\n- [ ] Slice chat per chunk.\n- [ ] Preserve break chat separately.\n- [ ] Add carry-forward chat to next spoken chunk.\n- [ ] Add next-chunk preview.\n- [ ] Commit chunk receipts and slices.\n\nChunk analysis:\n\n- [ ] Create Gemini prompt per chunk.\n- [ ] Attach MP4, prompt, transcript, chat, carry-forward chat, and preview.\n- [ ] Save Gemini raw result/log.\n- [ ] Verify `END_OF_VIDEO_ANALYSIS` sentinel.\n- [ ] Extract all required information from the response into local artifacts.\n- [ ] Close the completed Gemini tab only after extraction and sentinel verification;\n      leave active Gemini tabs and the browser profile alive.\n- [ ] Extract machine JSON.\n- [ ] Build `expected-items.json`.\n- [ ] Run coverage verification.\n- [ ] Run hallucination/timestamp/Q&A checks.\n- [ ] Run omissions pass if any gate fails.\n- [ ] Commit analysis and verification reports.\n\nVisual evidence:\n\n- [ ] Generate keyframe candidates.\n- [ ] Extract deterministic frames.\n- [ ] Extract Gemini-proposed frames.\n- [ ] Extract strips for visual demos.\n- [ ] Create contact sheet.\n- [ ] Review frames.\n- [ ] Downgrade unsupported visual claims.\n- [ ] Commit visual manifests/reviews.\n\nReconciliation:\n\n- [ ] Merge main analysis, omissions, verification, and keyframe review.\n- [ ] Write `final-reconciled.md/json` per chunk.\n- [ ] Preserve warnings.\n- [ ] Remove malformed URLs.\n- [ ] Deduplicate carried-forward overlap.\n- [ ] Commit reconciled chunks.\n\nFinal packet:\n\n- [ ] Generate final README.\n- [ ] Generate teammate guide.\n- [ ] Generate chapter index.\n- [ ] Generate resources and links.\n- [ ] Generate Q&A index.\n- [ ] Generate exercises.\n- [ ] Generate keyframes manifest.\n- [ ] Generate instructor checklist.\n- [ ] Run malformed URL scan.\n- [ ] Run URL resolution check if public.\n- [ ] Run final packet review.\n- [ ] Commit final packet.\n\nProcess documentation:\n\n- [ ] Save this process as `docs/repeatable-video-followup-process.md`.\n- [ ] Inspect for exact commands, mode branches, prompts, and gates.\n- [ ] Commit process doc.\n\n## Automation Responsibilities\n\nReview the process before automating it. These are proposed implementation boundaries, not supplied executables:\n\n```text\nscripts/video-followup/init-run.ts\nscripts/video-followup/probe-source.ts\nscripts/video-followup/detect-silence.ts\nscripts/video-followup/build-segment-manifest.ts\nscripts/video-followup/cut-chunks.ts\nscripts/video-followup/slice-transcript.ts\nscripts/video-followup/slice-chat.ts\nscripts/video-followup/build-gemini-prompts.ts\nscripts/video-followup/extract-machine-json.ts\nscripts/video-followup/verify-coverage.ts\nscripts/video-followup/scan-malformed-urls.ts\nscripts/video-followup/extract-keyframes.ts\nscripts/video-followup/build-contact-sheet.ts\nscripts/video-followup/reconcile-chunk.ts\nscripts/video-followup/build-final-packet.ts\ntemplates/gemini/chunk-analysis.md\ntemplates/gemini/omissions.md\ntemplates/oracle/planning-review.md\ntemplates/oracle/final-review.md\ntemplates/final/README.md\ntemplates/final/teammate-followup-guide.md\ntemplates/final/chapter-index.md\ntemplates/final/resources-and-links.md\ntemplates/final/instructor-review-checklist.md\ndocs/automation-roadmap.md\n```\n\nAutomation priority:\n\n1. Malformed URL scanner.\n2. Timestamp validator.\n3. Expected-items builder from chat/transcript.\n4. Chunk prompt generator.\n5. ffmpeg chunk cutter.\n6. Keyframe extractor/contact sheet builder.\n7. Final packet assembler.\n\n## Operational boundaries\n\n- Apply the media/privacy ignore policy before the example staging command. Do not stage raw recordings, chats, transcripts, or account-bearing screenshots merely because they live under `inputs/`.\n- Automation file lists are proposed boundaries, not supplied programs. Template fields must be filled from real evidence, and a sentinel is a completion signal rather than proof of accuracy.\n- The video-capable provider, browser routing, model aliases, upload limits, and cleanup commands are integration-specific. Verify the attached-video readiness probe and retain uncertainty when evidence is missing.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
