Writing Defect Reports

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 bo

115 stars 18 forksWriting & Content Plugin marketplace

Install

Claude Code plugin
/plugin marketplace add wdm0006/python-skills

The repo is a Claude Code plugin marketplace. Run /plugin afterwards to pick the plugin that includes this skill.

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add wdm0006/python-skills --skill writing-defect-reports
Manual install
git clone --depth 1 https://github.com/wdm0006/python-skills.git /tmp/python-skills
mkdir -p ~/.claude/skills
cp -r /tmp/python-skills/skills/common/defect-reports ~/.claude/skills/writing-defect-reports

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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](../verifying-external-behavior/SKILL.md) and
[testing-python-libraries](../../python/testing-strategy/SKILL.md). 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 (see [reporting-derived-metrics](../derived-metrics/SKILL.md)); 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:
Read the full skill on GitHub

Details

Skill name
writing-defect-reports
Path
skills/common/defect-reports/SKILL.md
License
MIT
Repo updated
18 November 2026

FAQ

What does the Writing Defect Reports skill do?

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 bo

How do I install the Writing Defect Reports skill?

Claude Code plugin: /plugin marketplace add wdm0006/python-skills. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Writing Defect Reports popular?

It lives in wdm0006/python-skills, which has 115 GitHub stars and 18 forks.

Related skills

Auditing Python Security

115

wdm0006/python-skills

Audits Python libraries for security vulnerabilities using Bandit, pip-audit, Semgrep, and detect-secrets. Identifies SQL injection, command injection, hardcoded credentials, secrets exposed through tracebacks, weak cryptography, and insecure deserialization. Use when reviewing library security, setting up security scanning in CI, or implementing secure coding patterns.

Security18

Building Accessible Interfaces

115

wdm0006/python-skills

Makes web and app UIs usable by keyboard, screen-reader, low-vision and motion-sensitive users — semantic HTML before ARIA, labelled controls, visible focus, WCAG AA contrast measured rather than eyeballed, touch targets, reduced motion, and automated axe checks plus a manual keyboard pass in CI or before every UI PR. Use when building or restyling a screen, adding a form, modal, menu or custom control, choosing colors, or reviewing a UI change.

Frontend & Design18

Building Browser Extensions

115

wdm0006/python-skills

Builds and tests Manifest V3 browser extensions — service-worker message channels that survive teardown, chrome.storage read-modify-write safety, settings validation in the popup, and a Jest chrome mock that can actually fail. Use when writing or reviewing a background service worker, a popup that reads/writes chrome.storage, an extension's Jest suite, or debugging an extension whose UI silently stops responding.

Software Development18

Crucible Editor

61

forsonny/The-Crucible-Writing-System-For-Claude

Revision and editing assistant for Crucible-drafted novels. Use when author has completed a first draft and wants to revise, edit, or polish their manuscript. Handles developmental editing, line editing, copy editing, and final polish. Triggers on "edit my novel," "revise chapter X," "polish my manuscript," "help me edit," or when user has completed draft chapters and wants to improve them.

Writing & Content21

Wp Acf and Content Modeling

116

jorgerosal/wordpress-skills

WordPress ACF and content modeling review for Codex. Use when reviewing ACF field groups, CPT and taxonomy design, options pages, repeaters, flexible content, relationship fields, ACF JSON sync, and meta-heavy content architecture.

Writing & Content13

Crucible Outliner

61

forsonny/The-Crucible-Writing-System-For-Claude

Chapter-by-chapter outline generator for stories planned with the Crucible Structure. Use when a user has completed Crucible planning documents (thesis, strand maps, forge points, etc.) and wants to create detailed chapter outlines. Triggers on requests like "outline my book," "create chapter outline," "outline Book 1," "turn my Crucible plan into chapters," or when user has Crucible planning docs and wants to start writing. Works for single books or multi-book series.

Writing & Content21

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.