# Writing Defect Reports

Establish a finding before you publish it, and correct it after, headlines that...

- Repository: https://github.com/kajisho5/ffmpeg-skill (4279 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add kajisho5/ffmpeg-skill --skill writing-defect-reports -g -a claude-code -y`
Codex: `npx skills add kajisho5/ffmpeg-skill --skill writing-defect-reports -g -a codex -y`
Cursor: `npx skills add kajisho5/ffmpeg-skill --skill writing-defect-reports -g -a cursor -y`
Gemini CLI: `npx skills add kajisho5/ffmpeg-skill --skill writing-defect-reports -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add kajisho5/ffmpeg-skill`

## Description

Establish a finding before you publish it, and correct it after, headlines that overstate what actually reproduces at the layer a user sees, reporting code that no entry point can reach or that is already dead, filing a caveat the project's own records already answered, re-verifying your prior notes against the tree instead of against the note, choosing the narrowest injection point that reproduces a failure without breaking the run first, capturing probe output a harness swallows, and withdrawing a published claim in the thread where you published it. Use when filing an issue, writing the body of a PR or code review that asserts a defect, triaging someone else's report, or deciding whether a suspicious observation is reportable at all.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Writing Defect Reports

A report is a claim, and it is read by people who will not re-derive it. The cost
of an overstated one is not embarrassment, it is a maintainer spending an
afternoon on a premise that does not hold, or a "fix" landing for a failure mode
that never occurred. The techniques for *finding* a defect live in
**verifying-external-behavior** (also in this repo's `.claude/skills/`). This
skill is about the step between finding one and publishing it.

The rule underneath all of it: **publish the claim you actually measured, at the
layer you measured it.**

## The anomaly is real; the headline may not be

The common failure is not a fabricated bug. It is a genuine internal oddity
promoted one layer too far.

You notice that a helper returns a degenerate value for a small sample, trace it
into a scoring path, and write the report as *"short inputs are wrongly flagged."*
Then you run real short inputs through the public entry point and the flag never
sets, a downstream threshold absorbs the degenerate value, and the only visible
effect is noise in a secondary per-feature list. The internal oddity is worth
fixing; the headline was false, and a reviewer who tests it will say so.

**Before writing the title, run the reproduction at the outermost layer the title
names.** Then choose one of three honest framings:

| what you measured                          | how to file it                              |
| ------------------------------------------ | ------------------------------------------- |
| reproduces end to end                      | file it as the user-visible symptom         |
| reproduces internally, absorbed downstream | file the internal defect, state the absorption |
| does not reproduce at all                  | do not file; record the probe and move on   |

The rest: https://github.com/kajisho5/ffmpeg-skill/blob/HEAD/.claude/skills/defect-reports/SKILL.md