Writing Defect Reports
Establish a finding before you publish it, and correct it after, headlines that...
Install
npx skills add kajisho5/ffmpeg-skill --skill writing-defect-reports -g -a claude-code -y- Repository
- kajisho5/ffmpeg-skill4.3k
- Category
- Git and review
- Updated
- 4d ago
- License
- MIT
- Context cost
- Mediumabout 2,841 tokens
- Runs scripts
- No, instructions only
What it does
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.
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 |
