TEMPLATESJIRA · BUG
Bug
A concise defect record with environment, reproduction steps, expected vs actual result and severity.
01Summary
Say what breaks, for whom, and where. Include the error if there is one. Avoid "not working".
[What fails] [where / for whom]
Example
Password reset link shows 500 error for existing users
02Environment
Fill in what a developer needs to recreate the conditions. Version and environment matter more than you'd think.
- App / service: [name] - Environment: [DEV / UAT / PROD] - Version / build: [number] - Browser / device: [if relevant]
Example
- App / service: Customer mobile app
- Environment: PROD
- Version / build: 4.12.1 (build 2087)
- Browser / device: iPhone 14, iOS 18.2
03Description
Two or three sentences: what's wrong, where it occurs, and since when. Facts only. Put guesses under Suspected Cause.
[What is wrong]. It occurs [where / when]. First seen [date or release].
Example
Customers who tap the reset link in the email see a "500 Internal Server Error" instead of the new-password screen. Seen since release 4.12.0 on 3 Nov, only for accounts created before 2024.
04Steps to Reproduce
Numbered, one action each, starting from a known state. If it only happens sometimes, say what you tried.
1. [Action] 2. [Action] 3. [Action]
Example
- Sign out of the app with a pre-2024 account.
- Tap "Forgot password" and request a reset.
- Open the email and tap the link.
05Expected Result
Say what should happen, ideally with a reference to the requirement or story.
[What should happen] (per [story / requirement])
Example
The new-password screen opens (per US-318).
06Actual Result
Say what really happens, including exact error text.
[What happens], including any error text
Example
A white page with "500 Internal Server Error" is shown. No new-password screen appears.
07Impact / Severity
Say who's affected and how badly. Pick severity from your own scale and say why, not just the label.
- User impact: [who, how many, what they can't do] - Severity: [Blocker / Critical / Major / Minor] - Frequency: [Always / Sometimes / Rare]
Example
- User impact: roughly 40,000 older accounts cannot recover access without calling support
- Severity: Critical
- Frequency: Always for affected accounts
08Screenshots / Logs
Attach what shows the failure. Trim logs to the relevant lines and remove personal data.
- [Link or attachment]
Example
- Screenshot of the error page
- API log extract, request id 7f3a-91c2
09Suspected Cause
Optional. If you have a lead, say so and how confident you are. It helps triage.
- [Hypothesis, and how you know]
Example
- Token lookup fails on legacy account ids (null tenant). Not confirmed.
10Workaround
Say what users or support can do today. If there isn't one, write "None".
- [Workaround, or "None"]
Example
- Support can issue a manual reset from the admin console.
11Acceptance Criteria
Define the fix in terms of the original behaviour and the cause. Not just "it works now".
- [ ] Root cause identified. - [ ] Fix implemented and peer reviewed. - [ ] Verification steps defined and executed.
Example
- Root cause documented: null tenant in token lookup.
- Fix merged with a regression test for legacy accounts.
- Reproduced steps 1 to 3 on build 4.12.2 with a pre-2024 account.
12Definition of Done (DoD)
Done means fixed where users are affected, verified, and linked back to what it broke.
- [ ] Fix deployed to the target environment. - [ ] Test case(s) executed and passed. - [ ] Release notes / comms updated if needed. - [ ] Ticket linked to the related story or requirement and closed.
Example
- 4.12.2 live in PROD on 14 Nov.
- TC-118 and new TC-125 passed.
- Support notified; release notes updated.
- Linked to US-318 and closed.