AI-Friendly Bug Reports: An Issue Template That Actually Works

A lot of “bug reports” are really feelings : “Sometimes it crashes.” “Login is broken.” “It’s slow.” Humans can often debug those anyway (by asking follow-up questions in chat). But if you want fast, reliable help from a teammate, an on-call rotation, or a coding assistant, you need something closer to a reproducible experiment than a complaint. In this post I’ll show you an issue template that produces bug reports your future self can actually work with. It’s optimized for clarity, reproduction, and safe sharing. The three failure modes of bad bug reports Most low-quality issues fail in one of these ways: Ambiguous contract : it’s unclear what “correct” behavior is. Non-reproducible : no steps, no data, no environment. Missing boundaries : the report includes everything except what matters (or it contains secrets you can’t share). A good template fixes all three by forcing the reporter to answer a small set of questions up front . The goal: reduce uncertainty, not add text A common mi