Skip to content

kajisho5/ffmpeg-skill / .claude/skills/code-review

reviewing-ffmpeg-skill-changes

Verified

Review 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.

FileKindSize
SKILL.mdskill md9.3 KB
references/result-honesty.mdmarkdown5.0 KB
references/review-checklist.mdmarkdown3.4 KB
references/reviewer-findings.mdmarkdown7.7 KB
references/surfaces.mdmarkdown3.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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall