kajisho5/ffmpeg-skill / .claude/skills/code-review
reviewing-ffmpeg-skill-changes
VerifiedReview a change to the ffmpeg-skill repository for the failures its own contract makes possible — a claim in a result document that is true at one layer and false at the layer a caller reads, a new flag that reaches the code but not the contract/docs/demo surfaces, a "bug" that docs/design-decisions.md already decided with a pinning test, a fix with no regression test, a new runtime dependency or a raw ffmpeg shell call that breaks the scope boundary, a SKILL.md line added without one trimmed, a review that re-derives findings from a summary instead of the tree at the reviewed commit. Use when asked to review a PR or diff in this repository, when authoring code here and needing a pre-commit check, or when triaging an external review or audit report about this codebase.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.3 KB |
| references/result-honesty.md | markdown | 5.0 KB |
| references/review-checklist.md | markdown | 3.4 KB |
| references/reviewer-findings.md | markdown | 7.7 KB |
| references/surfaces.md | markdown | 3.3 KB |
references/review-checklist.md
View on GitHub# Review Checklist — runnable
Copy this into the review. Every box is a command or a named read, not a feeling.
## 0. Base
```bash
git fetch origin
git log --oneline -1 origin/main
git diff --stat origin/main...HEAD
git diff origin/main...HEAD -- scripts/ docs/contract.md SKILL.md README.md
```
- [ ] Findings are stated against file:line at the reviewed commit
- [ ] `docs/design-decisions.md` grepped for each candidate finding; any match
cites the sentence that no longer holds
## 1. Result-document honesty
- [ ] `status` cannot be `completed` on a non-zero exit (`die()` sets `failed`)
- [ ] `verified` is a conjunction of steps that ran; nothing flipped to `true`
without a measurement
- [ ] `dropped_non_av_streams` matches timeline-move vs in-place (see
`result-honesty.md`)
- [ ] `cut` still reports `mode` / `keyframe_snapped` / `duration_delta_seconds`
- [ ] `error.kind` is the kind that actually occurred; `retryable` stays `false`
- [ ] `info()` still rewrites `wrote X` under `--dry-run`; no write claim in a
dry-run document
- [ ] `analysis_only` tools still measure under `--dry-run`
```bash
grep -rn "emit(\|die(" scripts/*.py | wc -l # every script ends in one of the two
python3 scripts/<changed-tool>.py --json --dry-run ... # read the document it prints
```
## 2. Surfaces
```bash
python3 scripts/_contract.py --json > /tmp/before.json # before the change
python3 scripts/_contract.py --json > /tmp/after.json # after
diff /tmp/before.json /tmp/after.json
wc -c SKILL.md # must be < 30000
```
- [ ] New flag/tool is in the contract, and `README.md` / `SKILL.md` /
`references/scripts.md` / `docs/contract.md` agree
- [ ] `CHANGELOG.md` has the entry
- [ ] `feat`: a demo in `demos/build.py` (or an `INSPECTION` row), `docs/demos.md`
regenerated with `python3 demos/build.py --docs`
- [ ] `SKILL.md` stayed under 30,000 bytes; the PR names the line it trimmed
- [ ] Release PR moved `docs/roadmap.md`'s "released version today" line
## 3. Scope and rules
- [ ] No new runtime dependency; stdlib + Python 3.10+ only
- [ ] No raw `ffmpeg`/`ffprobe` shell call outside `scripts/*.py`
- [ ] No mutation of an input file
- [ ] No AI/LLM content judgement, no cloud, no API keys
- [ ] Colour flags go through `validate_color(`; `--quality` range check stays in
`apply_common()`; time parsing goes through `time_arg()`
- [ ] A minor/patch change does not change the meaning of an existing field — a
parallel key (as `hdr_signal` was before 2.0) instead
- [ ] A fix ships a regression test that would have caught the original bug
## 4. The gate
```bash
npm test
npm run release-check
python3 scripts/_contract.py doctor
```
- [ ] Both test files pass, read after the run — not predicted
- [ ] Any red check is its own statement: what is red, what makes it red, whether
it was fixed, and whether it is pre-existing (run it on the base commit)
- [ ] Cross-OS / cross-FFmpeg risk stated for changes touching ffmpeg invocation,
path handling, or child-process decoding (CI covers FFmpeg 6.1–9.x on
Linux/macOS/Windows)
- [ ] No skip-CI marker quoted in the PR body
## 5. The write-up
- [ ] Findings ordered by cost: false claim → missing surface/test → style
- [ ] Each finding has file:line, the concrete failure, and the smallest fix
- [ ] Unverified items are labelled unverified, not implied passing
- [ ] Deep security audit deferred to a dedicated pass if warranted
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |