Template Bug Resolution Report
Bug / Known Issue Documentation Template
1. Issue Title
Format: [Area/System] – Short Description of Issue
Example:
[Provider Side Login] - Credentials are correct, but login fails without error message
2. Summary
One-paragraph explanation of the issue in plain language.
Explain:
- What goes wrong
- When it usually happens
- Who it affects
3. Systems / Area Affected
List where the issue occurs.
- Product area:
- Feature:
- Environment: (Production / Staging)
- Affected users: (Managers, Support, etc.)
4. Symptoms (How to Recognize This Issue)
Bullet list so non-technical users can confirm they are seeing the correct issue.
Users might see:
- Data reappears after navigating away and back
- No error message shown
- Redirected to a different page
5. Common Triggers
Situations that often cause the bug.
Examples:
- Refreshing the page
- Opening multiple dashboard tabs
- Returning to the dashboard after long inactivity
6. Quick Fix (Immediate Workaround)
Step-by-step instructions written for non-technical users.
Example:
- Navigate away from the dashboard (e.g., go to Reports).
- Return to Dashboard.
- Wait 5–10 seconds for the data to reload.
If the issue continues:
- Hard refresh the page (Cmd+Shift+R / Ctrl+Shift+R).
7. Prevention / How to Avoid It
Guidance to reduce the chance of the issue occurring.
Example:
- Avoid keeping the dashboard open in multiple tabs.
- If returning after a long time away, reload the page once.
8. Slack Example
Link to a real discussion where the issue occurred.
Slack Thread:
<Paste Slack link here>
Context:
Example case where a manager reported this issue and the workaround was applied.
9. When to Escalate
Clear rule for managers so they know when to report again.
Escalate if:
- The workaround does not resolve the issue
- The issue happens more than 3 times in a day
- Data appears incorrect (not just missing)
Report in:
#report-a-bug Slack channel
Include:
- Screenshot
- User affected
- Time issue occurred
10. Root Cause (Engineering Notes)
Technical explanation for internal teams.
Example:
Dashboard cache state sometimes fails to invalidate when session resumes, resulting in a null totals response.
11. Long-Term Fix (Proposed or Planned)
Engineering direction.
Example:
- Fix cache invalidation logic on dashboard load
- Add API retry for totals endpoint
Status:
- Proposed / In Progress / Released
12. Related Issues
Links to similar or connected bugs.
- Issue: Dashboard loading errors
- Issue: Reports showing delayed totals