Knowledge Video Decomposer

Knowledge Video Decomposer

Use this skill to turn source-gated transcript, subtitle, ASR, or approved local material into a structured knowledge package. In v0.6, platform acquisition is owned by acquire-source-material; this skill's old platform acquisition scripts are legacy compatibility paths.

Core workflow:

1. Inspect the source and collect metadata.
2. Before processing any video URL or platform page, read references/chrome-routing.md, references/chrome-probe-contract.md, references/source-status.md, and references/platform-prerequisites.md.
3. When starting a new platform workflow, diagnosing an environment failure, or handing the workflow to a new Agent, run scripts/doctor.py and save doctor_report.json / doctor_report.md under logs or 00_source. Doctor is read-only: it checks yt-dlp, ffmpeg/ffprobe, faster-whisper, Node.js, Chrome plugin files, cookies-file presence, Chromium App-Bound signals, Python encoding, and UTF-8 writing, but does not fetch media, launch Chrome, install extensions, or reveal cookie values.
4. Legacy only: use scripts/acquisition_runner.py for old first-pass platform acquisition probing. New URL acquisition should create 00_acquisition/manifest.json through acquire-source-material.
5. Legacy only: use scripts/platform_media_runner.py for old URL-to-material chains. New URL acquisition should be handed off through the acquisition bundle protocol.
6. Use scripts/acquisition_probe.py to record source status, source classes, failed probes, Chrome routing state, and the next allowed route when probe results already exist or when another tool produced the evidence.
7. Platform blocks, HTTP 429, bot/CAPTCHA/login barriers, RequestBlocked errors, or Hearsay URL timeouts on platform URLs must enter the Chrome route decision in references/chrome-routing.md instead of repeating the same extractor.
8. When a yt-dlp bare request or youtube_transcript_api hits a platform block (HTTP 429, bot check, sign-in required, RequestBlocked), first identify the browser that actually owns the authorized login state, then try --cookies-from-browser edge or --cookies-from-browser chrome as appropriate, or use a user-exported Netscape cookies.txt. Never infer the browser from the control-plugin name.
9. If the selected browser profile is locked or cookie decryption fails, do not loop over profiles or silently switch browser families. Follow references/platform-prerequisites.md: request approval before closing the actual browser, or request a user-exported Netscape cookies.txt; never read, display, copy, or commit cookie values.
10. If yt-dlp with cookies exposes only storyboards/images or reports n challenge solving failed, add a supported JavaScript runtime such as Node.js and, when accepted, --remote-components ejs:github before declaring media unavailable.
11. After yt-dlp with cookies, Chrome page inspection, or browser-derived probing obtains subtitles, audio, or a browser-visible transcript, that material must pass through source-status gating (references/source-status.md) before entering full decomposition.
12. Legacy/manual route: when Chrome opens a page and no visible transcript or caption UI is present, the old Chrome deep-probe sequence may still record observations, but new workflows should convert any user-approved transcript, subtitle, page text, or media export into an acquisition bundle before source-gate ingest.
13. Use references/chrome-probe-contract.md and scripts/chrome_media_probe.py for legacy normalization or manual adapter work only. Chrome observations must not bypass the source gate.
14. If Chrome deep-probe succeeds (an actual local media file or subtitle file was exported, or a public downloadable media/subtitle URL was confirmed and fetched), and subsequent ASR or subtitle parsing succeeds, the material qualifies as browser_derived_media - a primary source class that can support source_confirmed. Refer to references/source-status.md for the exact definition and recording requirements.
15. If no primary transcript, no browser-derived media, and no user-provided or legitimately acquired local file exists, stop full decomposition and request primary material. Record that the missing requirement is primary media/transcript, not merely a better prompt.
16. Prefer reliable existing subtitles or transcripts from the platform, yt-dlp (with the explicitly selected Edge/Chrome profile or user-exported cookies as needed), user-provided files, or local parsers - subject to the source-status gate.
17. Use scripts/asr_pipeline.py when a legitimate local audio/video file exists and subtitles/transcripts are unavailable or insufficient. The pipeline runs or resumes faster-whisper ASR, normalizes the transcript, records primary_audio_asr provenance, writes ASR quality, alignment, and diarization-compatible reports, and then hands off to segmentation. Missing word timestamps or speaker labels must degrade gracefully and must not turn ASR into a verified verbatim transcript.
18. Use scripts/transcript_normalizer.py to normalize local transcript/subtitle material (.txt, .md, .srt, .vtt, .jsonl, .json) into 01_transcript/raw_transcript.jsonl, 01_transcript/clean_transcript.jsonl, and 01_transcript/clean_transcript.md. The normalizer may open the decomposition gate for source-confirmed transcript material, but it must not write segments, inventory, logic, or video_analysis_pack.
19. Normalize transcript material into timestamped artifacts where timestamps exist, and record transcript provenance, language, confidence, and known limitations.
20. Use scripts/transcript_segmenter.py to segment confirmed/partial transcript material into 02_segments/subtitle_segments.json, 02_segments/syntax_segments.json, and 02_segments/argument_segments.json. Subtitle segments are a readability/timing layer; argument segments are the semantic/rhetorical layer. The segmenter may write 05_gap_check/segmentation_gap_check.md, but it must not write inventory, source logic, or video_analysis_pack.
21. Use scripts/inventory_extractor.py to extract candidate concepts, examples, claims, and analogies into 03_inventory/. Inventory entries must preserve evidence spans and remain candidates until source logic review verifies them. The extractor must not write source logic or video_analysis_pack.
22. Use scripts/source_logic_builder.py to reconstruct source-faithful speaker logic into 04_logic/source_logic.md and 04_logic/logic_graph.json. This stage may write source-logic gap notes, but it must not add external critique, downstream interpretation, or video_analysis_pack.
23. Use scripts/evidence_auditor.py after source logic exists to audit transcript, segment, inventory, and graph evidence. It writes 05_gap_check/evidence_audit.json, 05_gap_check/evidence_map.json, 05_gap_check/claim_source_audit.json, and 05_gap_check/gap_check.md; it must not write video_analysis_pack.md. Claims require transcript-backed spans, examples require concrete context, and source-logic nodes require transcript-backed evidence.
24. Use scripts/video_analysis_pack_builder.py only after 05_gap_check/evidence_audit.json, 05_gap_check/evidence_map.json, and 05_gap_check/claim_source_audit.json exist and the audit pack_gate allows a full or explicitly partial pack. This stage writes video_analysis_pack.md and must preserve the full/partial scope label.
25. Preserve evidence links to timestamps or source spans.
26. For Chinese, non-ASCII, Markdown, or JSON artifacts, use scripts/write_artifact.py, apply_patch, or another verified UTF-8 path. Do not write long Chinese artifacts through shell here-strings, inline command strings, PowerShell > redirection, or other paths that can silently change encoding or turn characters into question marks.
27. In source_blocked, source_failed, secondary_only, or degraded_report_only, do not pre-create the full analysis directory shape (01_transcript, 02_segments, 03_inventory, 04_logic, 05_gap_check) and do not create video_analysis_pack.md. Write only 00_source notes plus a clearly labeled degraded/acquisition report.
28. Validate outputs with scripts/artifact_validator.py before handing them downstream.
29. Output a video_analysis_pack for knowledge-document-composer only after evidence audit and validation pass for an allowed full or explicitly partial source status.

Runner guidance:

• Use scripts/doctor.py before acquisition when the environment is unknown, after a tool-path failure, or before long platform runs. Treat doctor failures as environment/setup issues, not source-content failures.
• Read the doctor setup_requirements table before declaring a source blocked or failed. yt-dlp, relevant media tools, Chrome plugin readiness, safe UTF-8 writing, and route-specific ASR/cookies/Node prerequisites must be separated from content availability.
• User-exported cookies, extension installation/approval, CAPTCHA/paywall/private/region permission, and local primary-material handoff are manual user steps. Do not automate or fake them.
• --youtube-cookies auto means only work/youtube-cookies/youtube.cookies.txt; it must not trigger Downloads scanning, browser-cookie extraction, full-disk search, or opening cookie contents.
• Legacy only: use scripts/acquisition_runner.py when reproducing older URL probe behavior. Listed subtitles or media formats are only available routes; they are not source_confirmed until a local subtitle/transcript/audio-derived transcript artifact exists.
• Legacy only: use scripts/platform_media_runner.py when reproducing older URL acquisition chains. Downloaded audio must still be followed by scripts/asr_pipeline.py; it is recorded as pending_primary_media_for_asr, not as primary_audio_asr.
• Legacy/manual adapter only: use scripts/chrome_media_probe.py after Chrome/pageAssets/Playwright inspection has produced layer observations. It writes standard Chrome deep-probe artifacts and suggests the acquisition signal, but it does not launch or control Chrome by itself.
• Use scripts/asr_pipeline.py for local audio/video that has been user-provided or legitimately acquired. It should produce 01_transcript/asr_transcript.jsonl, canonical clean_transcript artifacts, 00_source/asr_pipeline_report.json, 00_source/asr_pipeline_report.md, 00_source/asr_alignment_report.json, and 00_source/asr_diarization.json.
• Use scripts/transcript_normalizer.py after a transcript/subtitle file exists. It writes transcript artifacts and source-status metadata only; it does not perform semantic decomposition.
• Use scripts/transcript_segmenter.py after 01_transcript/clean_transcript.jsonl exists and source status is source_confirmed or explicitly partial. It writes 02_segments/subtitle_segments.json, 02_segments/syntax_segments.json, and 02_segments/argument_segments.json only and leaves inventory, source logic, and pack creation to later stages.
• Use scripts/inventory_extractor.py after 02_segments/argument_segments.json exists. It writes 03_inventory artifacts and inventory gap notes only; source logic and final pack creation remain later stages.
• Use scripts/source_logic_builder.py after 03_inventory exists. It writes 04_logic artifacts and source-logic gap notes only; final pack creation remains a later gated stage.
• Use scripts/evidence_auditor.py after 04_logic/logic_graph.json and 04_logic/source_logic.md exist. It writes final pre-pack gap artifacts plus evidence_map.json and claim_source_audit.json, then returns whether the next stage may build a full pack, a partial pack, or must fix evidence findings first.
• Use scripts/video_analysis_pack_builder.py after the evidence auditor returns enter_video_analysis_pack_builder or enter_partial_video_analysis_pack_builder and all evidence sidecars exist. It writes only video_analysis_pack.md and relies on the audit gate rather than reinterpreting source material.
• Use scripts/workflow_runner.py as a low-cost hard-gate runner for acquisition signals and minimal blocked/degraded status outputs.
• Do not treat workflow_runner.py as a full analyzer: it does not fetch media, launch Chrome, create transcripts, segment content, or produce a complete video_analysis_pack.

Read references/platform-prerequisites.md before processing YouTube or platform URLs where yt-dlp, cookies, JavaScript runtime, bot/sign-in checks, DPAPI/App-Bound failures, n challenge, missing subtitles, or local ASR routes may arise. Read references/chrome-routing.md and references/chrome-probe-contract.md before processing video URLs and whenever Chrome route, page-state, platform block, Hearsay URL timeout, 429, bot, CAPTCHA, login, RequestBlocked, visible-transcript, or Chrome deep-probe decisions arise. Read references/source-status.md before processing video URLs and before deciding whether full, partial, blocked, secondary-only, or degraded outputs are allowed. Read references/artifact-schema.md before writing intermediate artifacts. Read references/transcription-fallback.md before running ASR when reliable subtitles or transcripts are unavailable.