Bugs Template
docs/development/bugs.md uses a fixed shape, and so does docs/development/<app>/bugs.md in a workspace with several apps.
Purpose
Catalogs user-facing bugs in the current build. A reader scans bugs.md to know exactly what's broken for real users right now, sorted by impact.
Why
An agent can reproduce the actual bug and fix it.
Bug Vs Debt
- User-facing bug -> bugs.md.
- Test-tooling limitation, dev-mock gap, internal-only issue -> the debt list (Technical Debt Template).
- If real users never hit it, it's not a bug.
Sections
- Title:
# Bugs. - Overview list: flat dash list, one bullet per bug, formatted as
- <description> (`<priority>`). Always present, even when there's only one bug. Sorted by priority, highest first. - Per bug:
## <title>subheading, then the bug shape below.
Bug Shape
- Subheading:
## <user-perspective title>. The title is the user-experienced symptom, not the suspected cause. - Priority line right after the title:
Priority: <level>. Levels:high,medium,low(extend as needed). - Description paragraph: what the user experiences when the bug fires. Don't speculate on causes - speculation belongs in PR/commit discussion or investigation notes, not the bug doc.
### Reproducesubheading: steps that trigger the bug, ending withExpected:andActual:lines so the deviation is explicit. Reuse the matching spec use case's structure - the bug entry describes the deviation from the spec, not an alternate spec.### Referencessubheading: metadata bullets for navigation (Feature, Use case, E2E status).