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/surfaces.md

View on GitHub
# Surfaces — everywhere a fact about this repo is stated

A change is shipped only when every surface that states the fact agrees. `feat`
PRs are held to the full list below; a `fix` is held to whatever surface its fact
appears on.

## The inventory

| surface | what it must say | checked by |
| --- | --- | --- |
| `scripts/*.py` + `scripts/_contract.py` | the behaviour and the tool/flag schema | the generator |
| `python3 scripts/_contract.py --json` | canonical tool names, flags, dry-run semantics, error kinds | `tests/test_contract.py` |
| `README.md` | tool table, contract table, gotchas | tested against the contract |
| `SKILL.md` | runtime guidance for the calling agent | tested against the contract; < 30,000 bytes |
| `references/scripts.md` | per-tool detail | docs consistency tests |
| `docs/contract.md` | the contract restated for humans | `tests/test_contract.py` |
| `CHANGELOG.md` | the entry for the change | `test_changelog_mentions_every_closed_issue_since_last_tag` |
| `demos/build.py` → `docs/demos.md` | a before/after demo per feature | a test asserts every `scripts/*.py` appears in some demo |
| `mcp/` | MCP tools derived from the contract | MCP derivation tests |
| `bin/install.js` `PAYLOAD`, `package.json` `files` | what ships in npm | `tests/release_check.sh` |

## Rules a review enforces

- **Never hand-duplicate a schema.** Extend the generator in `_contract.py`. A
  schema typed into a doc by hand is drift waiting to happen.
- **A `feat` adds a demo** to the table in `demos/build.py`, then regenerates the
  page with `python3 demos/build.py --docs`. A tool whose entire output is a
  table, JSON document or HTML file goes in `INSPECTION` in `demos/build.py`
  instead of a demo.
- **A `feat` PR** updates `README.md`, `SKILL.md`, `references/scripts.md`,
  `docs/contract.md` and `CHANGELOG.md`. A feature only `SKILL.md` knows about is
  half shipped — the README is read by people who never open `SKILL.md`.
- **`SKILL.md` under 30,000 bytes** is a test
  (`test_skill_md_stays_under_the_30kb_budget`). Adding a line means trimming one;
  the PR says which.
- **A release PR moves `docs/roadmap.md`'s "the released version today is …" line
  in the same PR as the version bump**, so the roadmap never describes a shipped
  version as planned.
- **Packaging exceptions:** `references/process-pitfalls.md` is a maintainer diary
  and is deliberately *not* in the npm package; `scripts.md`, `devices.md`,
  `ci-platform-pitfalls.md` and `docs/contract.md` are. Check `package.json`
  `files` and `bin/install.js` `PAYLOAD`, not this note.
- **Never quote the release bump's skip-CI marker in a PR body.** A squash merge
  copies it into the merge commit and skips every workflow
  (`references/process-pitfalls.md`).

## Drift check

To confirm a surface is generated rather than restated, change the value in
`_contract.py` and re-run the contract tests; a surface that does not follow is
hand-maintained and is itself a finding.

```bash
python3 scripts/_contract.py --json > /tmp/before.json
# make the change
python3 scripts/_contract.py --json > /tmp/after.json
diff /tmp/before.json /tmp/after.json
npm test
```

For a refactor that must be behaviour-free (the `_common`/`text.py` splits are the
precedent), dump `--json` and every script's `--help` before and after and diff
them empty.
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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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