template · bug filing
Bug filing template
Copy-paste skeleton. Six dimensions, every bug. Severity, impact, type, environment, area, root cause. Chain level is the dimension teams skip — without it, every bug looks like a code defect.
How to use
Fill the six dimensions before assigning. Priority is auto-derived from Severity × Impact — never set manually. Root cause is named after the fix, not before — unknown is a temporary state, not an answer. CS does not file with chain-level — they file what they see; triage adds the chain level.
text
# BUG-NNN — [One-line symptom in user-facing terms]
Filed by: [Name (role)]
Filed at: YYYY-MM-DD HH:MM
Environment: production | staging | development
## What the user sees
[The symptom from the user's perspective. Not "the API returns
400" — "Gal sees 'submit failed' when she presses ⌘+Enter
after a 3-second pause."]
## Reproduction
1. [Specific steps from a clean state]
2. [...]
3. Observed: [what actually happens]
4. Expected: [what should have happened, with brief reference
if relevant]
## The six dimensions
Severity: P0 — Critical (data loss, security breach,
broken core flow)
P1 — High (significant degradation)
P2 — Medium (workaround exists)
P3 — Low (cosmetic, edge)
Impact: Blocker (cannot complete primary task)
High (severely degraded experience)
Medium (inconvenient)
Low (barely noticeable)
Priority: [AUTO — from Severity × Impact matrix]
Type: bug | regression | performance | security |
visual | copy | accessibility
Area: api | frontend | mobile | database | infra |
auth | payments | ux | [multiple if crosses
boundaries]
Reach: one | a segment | everyone
Reversibility: reversible | partial | irreversible
Root cause (operational — filled AFTER the fix):
requirements | logic-error | testing-gap |
data | configuration | dependency | unknown
Root cause (chain-aware — filled at triage or after fix):
scenario-gap | adr-drift | integration-gap |
observation-mismatch | n/a
## Linked artefacts
- Feature Brief: [link]
- Story / PR if known: [link]
- Runbook used: [link if incident]
- Postmortem: [link if elevated to incident]
## Notes
[Free-form. Logs, screenshots, related tickets, helpdesk pattern.]Priority matrix (auto-calculated)
| Severity ↓ / Impact → | Blocker | High | Medium | Low |
|---|---|---|---|---|
| Critical | P0 | P1 | P2 | P3 |
| High | P1 | P1 | P2 | P3 |
| Medium | P2 | P2 | P2 | P3 |
| Low | P3 | P3 | P3 | P3 |
- P0 — stop all work, incident process, stakeholders notified within 30 min.
- P1 — fix same day, escalate if blocked.
- P2 — normal backlog, no escalation unless ageing past 2 cycles.
- P3 — fix when capacity allows, review quarterly.
What good filing looks like
A filed bug runs through triage in 30 seconds because the six dimensions are there. A filed bug without dimensions absorbs triage time and produces no diagnostic value when the team reads chain-level distribution monthly.
Where this lives in your project
Bugs live in the team's tracker (JIRA, Linear, GitHub Issues). The chain-level label is the most important field for portfolio diagnosis — it shows up in the Portfolio Review pre-read. Without it, the bug tracker is a list; with it, the bug tracker is a diagnostic instrument.
What to do if a section resists
| Resistance | What it means | Where to go |
|---|---|---|
| Severity and Impact feel the same | They aren't — re-read the definitions | A critical security flaw used by 3 admins = High Severity, Medium Impact. A misaligned button blocking the primary CTA = Low Severity, Blocker Impact. |
| Cannot reproduce | Insufficient information at filing | Ask the reporter; if unavailable, mark data: insufficient and downgrade until reproducible |
| Multiple areas apply | The bug crosses boundaries | List all areas; this is itself diagnostic — boundary bugs are usually integration-gap |
| Root cause is "user error" | The team is dismissing the report | User errors are still data — what about the flow made the error easy? That is scenario-gap or observation-mismatch |
| Chain-aware root cause is blank | The taxonomy was skipped | The chain level is the diagnostic. Without it, the bug joins the noise; with it, the bug joins the map. |
Worked example — the wallet bug
text
# BUG-211 — Negative wallet balance displays as $0.00
Filed by: Maya (QA)
Filed at: 2026-05-08 11:14
Environment: staging
## What the user sees
A user with an actual balance of −$125.50 opens their dashboard
and sees "$0.00" in the wallet. They make decisions assuming
they have zero balance; if they had seen the true negative
balance, they would have acted differently.
## Reproduction
1. Seed a user account with `balance.amount = -125.50`
2. Open the dashboard view
3. Observed: "$0.00" displayed in green
4. Expected: "$-125.50" displayed in red per the design's
negative-balance state
## The six dimensions
Severity: High (financial data displayed wrong)
Impact: High (decisions made on bad data;
trust in every number erodes)
Priority: P1
Type: bug
Area: frontend
Reach: a segment (~8% of active users — those who
can go negative)
Reversibility: reversible (caught pre-production)
Root cause (operational): logic-error
(`balance.amount > 0 ? balance.amount : 0`
clamped every negative to zero)
Root cause (chain-aware): scenario-gap
(amigos session had no boundary-value
prompt for financial fields)
## Linked artefacts
- Feature Brief: /briefs/wallet-dashboard.md
- PR introducing: #201 (line 84 of WalletDisplay.tsx)
- Postmortem: n/a — caught in staging
## Notes
Maya found this during exploratory testing under the
"financial display under unusual balances" charter.
Structural fix: amigos template gains "boundary-value
prompt for financial fields" — see retro action 2026-05-08.See also
- Template — Daily triage — what runs over filed bugs
- Template — Postmortem — when a bug becomes an incident
- Template — Runbook — the mitigation reference for live bugs
- Canon — After We Build · Bugs and Their Roots · Severity × Impact · Root causes · Worked example: wallet bug