video-content-analysis

/analyze-video <path> produces a manifest-led artefact pack from one video file. Downstream specialists (qualitative-coding-specialist, intersectionality-analyst, gender-transformative-assessor, sbcc-campaign-mel-specialist) consume the manifest directly.

When to use

Trigger for any request that names a video, recording, FGD, webinar, training session, or SBCC clip and asks for transcript, summary, speaker analysis, or downstream coding. Trigger when Ane types /analyze-video <path> directly.

Do not trigger for live audio capture (file-based only in v1) or non-video media (audio-only files are out of v1 scope).

Required inputs

Ask in one batch. The first three are required.

1. Video path (required). Local file. Supported containers: mp4, mkv, mov, webm.
2. Privacy tier (required). One of sensitive, internal, public. Default sensitive. Sensitive content (FGDs, interviews, anything with informed-consent constraints) stays on the local machine. Internal/public content can use Microsoft 365 Stream captions when available.
3. Consent status (required). One of notapplicable, consentinternaluseonly, consentresearchanonymised, consentresearchattributed, consentpublicationanonymised, consentpublicationattributed, consentunclear. consentunclear blocks downstream analysis.
4. Language hint (optional). Two-letter code for Whisper (e.g. ro, en, fr). Omit to auto-detect.
5. Run diarization? (optional, default no). --diarize runs pyannote.audio after transcription. Required for whose-voices-were-heard analysis. Adds ~50% to runtime.
6. Brand-template Word summary? (optional, default no). --brand-summary writes summary.docx in IPPF Visual Identity 2025 alongside the plain summary.md.
7. Output directory (optional). Default <video-parent>/<video-stem>.video-analysis/.
8. Microsoft 365 caption file (optional, internal/public only). Local .vtt path the user has already fetched via the Microsoft 365 MCP server. Skips Whisper.

Method

Step 1 — gather inputs

Ask Ane for required inputs 1–3 in one message. If --diarize, --brand-summary, or a caption path were passed in the invocation, do not re-ask. Honour the explicit values.

Step 2 — capture consent metadata when missing

If consent metadata is incomplete (status set but no documentedin / documenteddate / responsible_person), ask Ane in a second focused batch. Persist the captured values into the orchestrator call so they land in the manifest.

Step 3 — invoke the orchestrator

Use Bash to run the venv Python with a one-line analyze_video(...) call. Force the ffmpeg PATH extension before the run. Pass the captured kwargs.

$env:PATH = "$env:LOCALAPPDATA\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1.1-full_build\bin;$env:PATH"
& 'C:/Users/AGasser/OneDrive/GitHub/personal-skills/skills/video-content-analysis/venv/Scripts/python.exe' -c @'
from pathlib import Path
from ane_package.video.orchestrator import analyze_video
from ane_package.video.types import ConsentMetadata, ConsentStatus, PrivacyTier
result = analyze_video(
    Path(r"<VIDEO PATH>"),
    privacy_tier=PrivacyTier.<TIER>,
    consent=ConsentMetadata(
        status=ConsentStatus.<STATUS>,
        documented_in=r"<PATH OR NOTE>",
        documented_date="<ISO DATE OR EMPTY>",
        responsible_person="<NAME OR EMPTY>",
    ),
    language=<"ro" OR None>,
    diarize=<True OR False>,
    brand_summary=<True OR False>,
    output_dir=<PATH OR None>,
    m365_caption_path=<PATH OR None>,
)
print("MANIFEST:", result.manifest_path)
print("SUMMARY:", result.summary_path)
print("BRAND_SUMMARY:", result.brand_summary_path)
'@

Step 4 — print the Tier 1 BLUF summary inline

Read summary.md from the orchestrator's return value and print it in the conversation. Add the manifest path on a final line so Ane can hand it to /ann or to a specialist.

Step 5 — per-run feedback prompt

Run the feedback prompt before returning. Use the venv Python:

& 'C:/Users/AGasser/OneDrive/GitHub/personal-skills/skills/video-content-analysis/venv/Scripts/python.exe' -c @'
from ane_package.video.feedback import prompt_verdict
v, n = prompt_verdict()
print(f"VERDICT={v.value}")
print(f"NOTE={n or ''}")
'@

If the verdict is partial or failed, append the verdict and note to ~/.claude/skills/video-content-analysis/telemetry.jsonl so the next retrospective sees them. The orchestrator already wrote a telemetry line for the run; this second write is a verdict update keyed by source_hash. (Stage 6 collapses these into a single in-orchestrator call when the prompt timing is reworked.)

Saving a regression fixture (verdict: partial / failed)

When a run finishes with partial or failed, the skill offers to save it as a regression fixture under tests/video/fixtures/auto/<source_hash>/.

Tier-gated:

• privacy: public AND consent: notapplicable | consentpublication_* → full save (source + transcript + frames + manifest)
• any other eligible verdict → metadata-only save (redacted manifest with consent + speaker labels + transcript text + source path stripped)
• consent_unclear → blocked entirely (regardless of verdict)

The auto-save directory is gitignored — auto-saved fixtures are local-only until you review and selectively commit.

Step 6 — return

Return the manifest path, the summary path, and (if any) the brand-summary path to Ane. Suggest the next move:

• "Run /ann analyse the focus group findings in <manifest>" — for in-depth coding.
• "Run /ann compute speaker time-share by gender across these 3 manifests" — for batch cross-cuts.
• "Open summary.docx for the slide deck" — when --brand-summary was passed.

Running the retrospective protocol

/analyze-video --retrospective

Reads ~/.claude/skills/video-content-analysis/telemetry.jsonl, computes performance against the seven anchors at mel_wiki/wiki/calibration/video-content-analysis.md, identifies recurring failures, and writes ~/.claude/skills/video-content-analysis/retrospectives/retrospective-YYYY-MM-DD.md.

Recommendations only. The retrospective never edits the skill, the spec, or any code. Ane reviews and approves before any change ships.

The retrospective also fires automatically when shouldrunretrospective(state) returns True at the end of any successful /analyze-video run — i.e., after 10 successful runs OR 4 weeks since the last retrospective, whichever is first.

Output

• manifest.json — single source of truth for downstream specialists.
• summary.md — Tier 1 BLUF summary, plain markdown.
• summary.docx — IPPF Visual Identity 2025 brand template (when --brand-summary).
• transcript.json / transcript.txt / transcript.vtt — populated by the primitives.
• frames/ — sequentially-numbered PNG frames.
• network.log — one-line audit trail.

Calibration anchors

Operational quality benchmarks for this skill live at mel_wiki/wiki/calibration/video-content-analysis.md in the work folder.

Seven anchors:

• Schema validity (100% of manifests pass manifest_v1.schema.json)
• Transcription quality — Romanian (WER < 15% on the synthetic Romanian FGD fixture)
• Privacy enforcement (zero network_egress != none under sensitive tier)
• Consent enforcement (zero deliverables published from consent_unclear material)
• Data-gap detection (every audioqualityflags[] flag maps to a data_gaps[] line; confidence-based extension gated on Stage 4.5)
• Performance (60-min FGD with diarization < 90 min wall-clock on this hardware)
• User satisfaction (≥ 80% of last 10 runs verdict ∈ {useful, partial})

The retrospective protocol consumes these anchors. See the section above.

Evidence base: Stage 5 implementation plan at docs/superpowers/plans/2026-05-09-stage-5-skill-orchestrator.md; design spec at docs/superpowers/specs/2026-05-08-video-content-analysis-design.md Sections 5–8 + 10; IPPF Visual Identity 2025 brand template at anepackage.reporting.brand.IPPFFORMAT_TEMPLATE.