docs(research): add media evidence routing (#483)

2026-09-11 19:47:12 +03:00 · 2026-09-08 09:41:53 -04:00
parent b4669acf4c
commit addad86018
10 changed files with 143 additions and 6 deletions
@@ -1092,7 +1092,7 @@
        "./research-methodology"
      ],
      "strict": false,
-      "description": "Plan, conduct, evaluate, and synthesize rigorous research investigations with credible evidence and a traceable method. Do not use this skill for repeated source extraction and durable note orchestration; use `research-and-vault` for that capture workflow."
+      "description": "Plan, conduct, evaluate, and synthesize rigorous research investigations with credible evidence and a traceable method, including source-to-claim closure for media evidence. Do not use this skill for repeated source extraction and durable note orchestration; use `research-and-vault` for that capture workflow, or `ffmpeg` for media operations."
    },
    {
      "name": "resilience-and-recovery",
@@ -183,6 +183,19 @@
        "does not claim compatibility with every platform and leaves upload operations to the owning platform skill"
      ],
      "case_set": "release"
+    },
+    {
+      "id": "media-research-routing-boundary",
+      "prompt": "Build a defensible research record for an FFmpeg behavior claim and a sparse-frame editorial claim. I need source-to-claim traceability, not another command recipe.",
+      "expected_output": "Route research scope, source/access-date evaluation, exclusions, claim closure, and durable preservation to research-methodology while retaining FFmpeg build, command, probe, fixture, sample, and target evidence in this skill. Keep documented semantics, reproduced behavior, observed artifacts, heuristics, and human review separate, and refuse editorial or whole-asset conclusions beyond sampled evidence.",
+      "assertions": [
+        "routes general research method to research-methodology and operational media evidence to ffmpeg",
+        "records official source URLs and access dates plus exact local build and experiment conditions",
+        "preserves rejected, inaccessible, redundant, and untested sources with reasons",
+        "audits sampling coverage against the scope of each claim",
+        "keeps technical findings separate from attributed editorial approval"
+      ],
+      "case_set": "release"
    }
  ]
 }
@@ -2,6 +2,8 @@

 Use this index to connect a media claim to the strongest available source. Prefer official documentation for FFmpeg semantics, local evidence for installed capability, controlled experiments for uncertain behavior, and attributed review for editorial judgments.

+Research scope, source evaluation, exclusion logging, source-to-claim closure, and sampling-completeness audits follow [`research-methodology` media-evidence routing](../../research-methodology/references/media-evidence-routing.md). This FFmpeg reference owns the media-specific source hierarchy and the operational evidence returned to that method; it does not duplicate the general research lifecycle.
+
 ## Official FFmpeg sources

 | Claim area | Official source | Supports | Does not establish |
@@ -122,7 +122,7 @@
 - [release-engineering](release-engineering/SKILL.md): Design, automate, and operate end-to-end software releases: release process models and pipelines (trunk-based development, CD stages, release trains), progressive delivery and feature flags, versioning and artifact management (SemVer, conventional commits, changelogs, SBOM/provenance), readiness and quality gates, rollback and recovery planning, change-management and audit compliance (SOC 2, SOX, PCI), DORA metrics, and multi-team release coordination. Do not use for application feature implementation (backend-engineering/frontend-engineering), production incident root-cause debugging or on-call/SLO operations (systematic-debugging / site-reliability-engineering), security implementation or threat modeling (secure-software-engineering), or internal developer platform construction (platform-engineering).
 - [remote-systems-administration](remote-systems-administration/SKILL.md): Administer and troubleshoot remote Linux, FreeBSD, NetBSD, OpenBSD, and macOS systems safely, one host or a fleet at a time. Use when a task requires SSH, Ansible, Paramiko, POSIX diagnostics, service management, software updates, system configuration, firewall changes, or evidence-led remote operations. Do not use for local-only desktop administration, container or cluster orchestration (route to kubernetes), or cloud consoles that expose no remote shell.
 - [research-and-vault](research-and-vault/SKILL.md): Chain web research, atomic extraction, and durable note capture when the same research-to-notes sequence must repeat. Do not use this skill to design or evaluate an investigation; use `research-methodology` for research questions, methods, and evidence assessment.
- [research-methodology](research-methodology/SKILL.md): Plan, conduct, evaluate, and synthesize rigorous research investigations with credible evidence and a traceable method. Do not use this skill for repeated source extraction and durable note orchestration; use `research-and-vault` for that capture workflow.
+- [research-methodology](research-methodology/SKILL.md): Plan, conduct, evaluate, and synthesize rigorous research investigations with credible evidence and a traceable method, including source-to-claim closure for media evidence. Do not use this skill for repeated source extraction and durable note orchestration; use `research-and-vault` for that capture workflow, or `ffmpeg` for media operations.
 - [resilience-and-recovery](resilience-and-recovery/SKILL.md): Design, exercise, and evidence graceful degradation, disaster recovery, and restoration behavior across systems and dependencies. Covers failure-mode analysis, RTO/RPO decision records, restore testing, game days, failover drills, data integrity verification, and recovery communication. Do not use for live incident command or incident response; route to site-reliability-engineering for those. Do not use for infrastructure implementation details; route to platform-engineering.
 - [restic](restic/SKILL.md): Install, configure, operate, secure, automate, tune, troubleshoot, and recover restic backups across local, SFTP, S3-compatible, cloud, and REST backends. Use when creating or managing a restic repository, designing backup or retention policy, validating restores, handling repository health or locks, moving repositories, or building safe scheduled backup jobs. Do not use for a generic file-copy task that does not need encrypted, deduplicated snapshots.
 - [secure-software-engineering](secure-software-engineering/SKILL.md): Use when designing or implementing software securely: define security requirements, threat-model a feature, choose secure defaults, design authentication and authorization, handle untrusted data and secrets, evaluate dependencies, design multi-tenant trust boundaries, or review security-sensitive changes. Use for prevention during requirements, design, implementation, and review; not for post-build security assessments or scanning an existing codebase.
@@ -13,13 +13,15 @@ Use it when the work needs a repeatable process and an inspectable result. It is
 | Path | What it provides |
 |---|---|
 | `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
-| `references/` | Reference material: `industry-analysis.md`, `journalistic-research.md`, `research-lifecycle.md`, `source-evaluation.md`, `structured-analytic-techniques.md`, `synthesis-patterns.md`, `technical-verification.md` |
-| `assets/` | Assets: `research-brief.md`, `research-log.md`, including a durable-artifact inventory and source-to-artifact preservation ledger. |
+| `references/` | Journalistic, industry, comprehensive, technical-verification, source-evaluation, synthesis, and media-evidence routing guidance. |
+| `assets/` | Research brief/log plus a media claim ledger for source-to-experiment closure and sampling audits. |

 ## Quick Start

 Choose the research track in `SKILL.md`, then start from `assets/research-brief.md` and maintain a research log. Preserve the retained evidence and extracted claims in the long-lived research surface your agent and users normally use before delivering the synthesis.

+For research involving media, also copy `assets/media-claim-ledger.md`. Use this skill to audit claims and evidence; use the `ffmpeg` skill for probes, extraction, experiments, editing, and verification.
+
 Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.

 ## Triggers
@@ -27,6 +29,7 @@ Install or expose this directory using your agent's standard Agent Skills loadin
 - Plan, conduct, evaluate, and synthesize rigorous research. Use for journalistic, industry, or technical investigations that need credible evidence and a traceable method.
 - Requests involving the method, deliverables, or review process described in `SKILL.md`.
 - Work where a reusable template or reference from this skill would reduce avoidable mistakes.
+- Media research that needs sourced technical claims, build-specific reproduction records, sampling-completeness checks, or a clean handoff between FFmpeg evidence and human editorial judgment.

 ## Requirements

@@ -2,8 +2,9 @@
 name: research-methodology
 description: >-
  Plan, conduct, evaluate, and synthesize rigorous research investigations with credible
-  evidence and a traceable method. Do not use this skill for repeated source extraction
-  and durable note orchestration; use `research-and-vault` for that capture workflow.
+  evidence and a traceable method, including source-to-claim closure for media evidence.
+  Do not use this skill for repeated source extraction and durable note orchestration;
+  use `research-and-vault` for that capture workflow, or `ffmpeg` for media operations.
 license: MIT
 compatibility: No runtime dependency. Use appropriate retrieval tools and retain source URLs and access dates in the research log.
 metadata:
@@ -22,6 +23,8 @@ Professional research process for a subagent. Three tracks based on the type of

 All three share the same lifecycle (Scope → Gather → Evaluate → Analyze → Synthesize → Report) but differ in evidence standards, speed, and output format.

+Media evidence is a technical-verification extension, not a fourth operational track. This skill owns research scope, source evaluation, claim closure, sampling-completeness audits, exclusions, and durable preservation. The `ffmpeg` skill owns FFmpeg commands, media probes, extraction, editing, rendering, and target verification; human or capable reviewers own semantic/editorial observations and approval. Load `references/media-evidence-routing.md` whenever a research conclusion depends on media tooling, sampled frames/audio/transcripts, or editorial judgment.
+
 ## When not to use

 Do **not** load this skill for:
@@ -86,6 +89,7 @@ The acceptance gate is evidence completeness and artifact verification, not elap
 | `references/structured-analytic-techniques.md` | You need to evaluate competing explanations — ACH, driving forces, pre-mortem, indicators |
 | `references/synthesis-patterns.md` | You need to combine findings from multiple sources into synthesized conclusions |
 | `references/technical-verification.md` | You need to test a technical claim by reproducing it — benchmarks, API behavior, configuration |
+| `references/media-evidence-routing.md` | Media research needs an explicit research/FFmpeg/reviewer boundary, sampling audit, or source-to-claim closure |

 ### Assets

@@ -93,6 +97,7 @@ The acceptance gate is evidence completeness and artifact verification, not elap
 |-------|-----------------|
 | `assets/research-brief.md` | Structured brief with findings, confidence assessment, evidence table, open questions |
 | `assets/research-log.md` | Traceable record of searches, sources, and decisions |
+| `assets/media-claim-ledger.md` | Media brief boundary, claim-to-source/experiment closure, sampling audit, and exclusion log |

 Use both assets for every substantial investigation. Before closing the work, complete their durable-artifact sections and verify that retained sources and extracted claims are represented in the destination system.

@@ -0,0 +1,37 @@
+# Media Claim Ledger
+
+## Brief Boundary
+
+- Decision and objective:
+- Output contract / target:
+- Rights, privacy, retention, and sharing boundary:
+- Decision granularity:
+- Required sampling coverage:
+- Human review points:
+
+## Claim Closure
+
+| Claim ID | Exact claim and scope | Evidence class | Source URL / locator | Access date | Tool/build and experiment | Artifact/interval | Result | Limitation / counter-evidence | Durable artifacts | Status |
+|---|---|---|---|---|---|---|---|---|---|---|
+| media-001 | | documented / reproduced / observed / environment-specific / heuristic / unresolved | | | | | | | | open |
+
+## Sampling Audit
+
+| Claim ID | Population / interval claimed | Sampling method | Covered timestamps / streams | Transformations | Blind spots | Supports claim scope? | Next evidence or reviewer |
+|---|---|---|---|---|---|---|---|
+| media-001 | | | | | | yes / no / partial | |
+
+## Rejected and Untested Sources
+
+| Source / proposed test | Rejected / inaccessible / redundant / untested / blocked | Reason | Consequence for confidence | Revisit trigger |
+|---|---|---|---|---|
+| | | | | |
+
+## Completion Gate
+
+- [ ] Current technical claims include source URLs and access dates.
+- [ ] Reproduced claims include exact versions/builds, fixtures, commands, probes, and raw evidence.
+- [ ] Every sample states its stream/interval, selection method, transformations, coverage, and blind spots.
+- [ ] No whole-asset or editorial conclusion is based only on sparse technical evidence.
+- [ ] Technical findings and attributed editorial approval are separate.
+- [ ] Each retained claim links to durable artifacts; exclusions and unresolved questions are logged.
@@ -85,6 +85,18 @@
        "Recognizes the request sits outside the skill's trigger boundary — a single factual lookup answered without the full process",
        "Imposes no unnecessary scoping, triangulation, logging, or artifact machinery on a trivial lookup"
      ]
+    },
+    {
+      "id": "media-claim-source-experiment-closure",
+      "prompt": "Research whether sparse FFmpeg frame samples prove that a logo never appears anywhere in a two-hour video. Keep the work reproducible and tell me which skill owns what.",
+      "expected_output": "Use research-methodology for question scope, sources/access dates, exclusions, claim closure, sampling audit, and durable artifacts; route FFmpeg commands, probes, extraction, and build-specific experiments to the ffmpeg skill; and route semantic/editorial judgment to an attributed reviewer. Reject the whole-video absence conclusion because sparse samples cover only sampled timestamps, then narrow the claim, collect sufficient bounded evidence, or leave it unresolved.",
+      "assertions": [
+        "makes the ownership boundary between research-methodology, ffmpeg, and the reviewer explicit",
+        "requires source URLs and access dates for current documented claims and exact versions/builds for reproduced claims",
+        "records asset/stream/interval, sampling method, transformations, coverage, and blind spots",
+        "rejects a whole-video or editorial conclusion from sparse technical samples",
+        "maps each claim to source, experiment, limitation, durable artifact, and exclusion or unresolved status"
+      ]
    }
  ]
 }
@@ -0,0 +1,61 @@
+# Media Evidence Routing
+
+Use the shared research lifecycle for media questions, but keep operational media mechanics with the owning tool skill. This reference defines the handoff; it is not an FFmpeg runbook.
+
+## Ownership boundary
+
+| Concern | Owner |
+|---|---|
+| Research question, inclusion/exclusion rules, source evaluation, current-claim dates, rejected-source log, source-to-claim audit, synthesis confidence, and durable preservation | `research-methodology` |
+| FFmpeg/FFprobe commands, build inventories, media intake, bounded extraction, EDLs, rendering, signal measurement, and output/target verification | `ffmpeg` |
+| Transcript acquisition and timing quality | The authorized source or transcription skill |
+| Semantic frame/audio interpretation and editorial approval | An attributed human or capable reviewer |
+| Upload, account, or platform API action | The named platform skill |
+
+Start from `assets/research-brief.md` and `assets/research-log.md`. For consequential media claims, also copy `assets/media-claim-ledger.md`. Route command selection and experiment execution to `ffmpeg`; return its versioned records to the research ledger before synthesis.
+
+## Media brief additions
+
+Record these before gathering evidence:
+
+- editorial or technical objective and the decision it will inform;
+- output contract and named downstream consumer, if any;
+- rights, authorization, privacy, retention, and sharing boundary;
+- decision granularity: whole asset, interval, event, frame, packet, or stream;
+- review points and accountable human decisions;
+- required coverage and what would make sampling insufficient.
+
+## Evidence classes
+
+Keep unlike evidence separate:
+
+- **Documented semantics:** an official specification or tool manual, with URL, accessed date, relevant version, and exact supported claim.
+- **Reproduced behavior:** exact tool/build, environment, fixture/digest, commands, raw results, and repeated observations.
+- **Observed artifact:** probe fields, decoded samples, measurements, destination results, or attributed review for the named artifact and interval.
+- **Environment-specific claim:** availability or behavior tied to one build, device, operating system, target, or account.
+- **Heuristic:** detector threshold, sparse sampling, transcript navigation, inferred continuity, or editorial convention requiring review.
+- **Unresolved:** conflicting, inaccessible, untested, undersampled, or authorization-blocked claim.
+
+Official documentation explains documented behavior; it does not prove local availability or the outcome of a command. A reproduction establishes only its recorded fixture and conditions. A target result applies only to that target/version.
+
+## Sampling and editorial guardrails
+
+Every frame, clip, waveform, transcript span, or detector event needs an asset ID, stream/interval, selection method, transformations, and coverage statement. Audit whether the sample can support the claim's scope. Sparse frames cannot establish absence throughout a video; a detector event cannot establish editorial meaning; a transcript cannot establish exact audiovisual continuity; a local decode cannot establish downstream acceptance.
+
+When coverage is insufficient, narrow the claim, collect more bounded evidence, request attributed review, or leave the question unresolved. Technical facts and human editorial approval remain separate ledger entries.
+
+## Worked source-to-claim closure
+
+This compact example demonstrates the method, not a portable compatibility guarantee.
+
+| Field | Record |
+|---|---|
+| Claim | Explicit stream mapping preserved one MPEG-4 video stream followed by one PCM audio stream in a Matroska remux under the recorded experiment. |
+| Classification | Reproduced behavior plus observed artifact. |
+| Source | [FFmpeg documentation](https://ffmpeg.org/ffmpeg.html), accessed 2026-09-08; supports `-map` stream-selection semantics, not this run's outcome. |
+| Experiment | Synthetic 64x64/10 fps video plus 48 kHz sine audio; FFmpeg and FFprobe 8.1.2; create source, remux with `-map 0:v:0 -map 0:a:0 -c copy`, then probe stream index/type/codec. |
+| Observation | FFprobe reported stream 0 as MPEG-4 video and stream 1 as PCM signed 16-bit little-endian audio. |
+| Limitation | One local build, synthetic fixture, Matroska container, and one stream order. This does not establish visual/audio quality, exact timing, other builds/containers, or downstream compatibility. |
+| Durable artifacts | Claim ledger entry, access-dated source record, exact command log, build record, source/output probe JSON, fixture generator, and rejected/untested-source entries. |
+
+Closure requires the claim to link to every named artifact and the durable log to record missing evidence. Preserve inaccessible, rejected, redundant, and untested sources with reasons so omission cannot masquerade as coverage.
@@ -77,3 +77,7 @@ For technical tutorials and walkthroughs (like "Running a 35B MoE Model on a 16G
 - If a configuration didn't work, say so and explain why

 This standard distinguishes evidence-led technical writing from generic tutorials. The mistakes and dead ends are often the value.
+
+## Media-specific verification
+
+When a technical claim depends on media streams, sampled frames/audio/transcripts, an editorial interpretation, or a downstream consumer, load `media-evidence-routing.md`. The shared reproduction standard still applies, but the `ffmpeg` skill owns command/build/media mechanics. Preserve its probes, commands, samples, and target results in `../assets/media-claim-ledger.md`; do not infer whole-asset or editorial conclusions from sparse technical samples.