Bug Report
Turn "it's broken" into a proper bug report. Structured, actionable, developer-ready.
What It Does
Takes a rough bug description and generates:
- Title (concise, searchable)
- Reproduction steps (numbered, specific)
- Expected vs actual behavior
- Severity and priority classification
- Environment details template
- Suggested investigation areas
- Related patterns (common causes for this type of bug)
Usage
From description:
bug-report "login page crashes when I use special characters in password"
With context:
bug-report "API returns 500 on large file uploads" --component "upload-service" --env "production" --frequency "always"
Options:
--component — affected component/service--env — environment where it occurs: production, staging, development, local--frequency — always, intermittent, once, unknown--user-impact — blocking, major, minor, cosmetic--format — markdown (default), json, github (GitHub issue template)--template — standard (default), jira, linear, github
Generation Rules
Title:
- Under 80 characters
- Pattern:
[Component] Short description of the defect
- Include the failing action and the symptom
- Good: "Login page crashes with special characters in password field"
- Bad: "Bug in login" or "Page doesn't work"
Reproduction Steps:
- Start with preconditions (logged in/out, specific data state)
- Number each step
- Be specific ("Click the Submit button" not "Submit the form")
- Include exact input data where relevant
- End with the step that triggers the bug
Severity Classification:
| Severity |
Criteria |
Examples |
| Critical |
System crash, data loss, security vulnerability, no workaround |
App crashes on launch, data corruption, auth bypass |
| High |
Major feature broken, significant user impact, workaround exists but painful |
Can't upload files (core feature), slow response (>30s) |
| Medium |
Feature partially broken, workaround available, moderate impact |
Sort order wrong, pagination off by one |
| Low |
Minor inconvenience, cosmetic, rarely encountered |
Typo in error message, alignment issue, tooltip wrong |
Priority (separate from severity):
| Priority |
When to Fix |
| P0 |
Immediately (production down, security breach) |
| P1 |
This sprint / within 48 hours |
| P2 |
Next sprint / within 2 weeks |
| P3 |
Backlog / when convenient |
Investigation Suggestions:
Based on the bug type, suggest where to look:
| Bug Pattern |
Investigation Areas |
| Crash on input |
Input validation, character encoding, buffer limits |
| 500 error |
Server logs, exception handler, request payload size |
| Intermittent failure |
Race conditions, caching, timeouts, connection pooling |
| Wrong data |
Query logic, data transformation, timezone handling |
| UI glitch |
CSS specificity, viewport handling, browser compatibility |
| Performance |
Database queries, N+1 problems, memory leaks, missing indexes |
| Auth issues |
Token expiry, session handling, CORS, cookie domain |
Output (Markdown):
# [Upload Service] API returns 500 on large file uploads
**Severity:** High | **Priority:** P1 | **Component:** upload-service
**Environment:** Production | **Frequency:** Always
**Reported:** 2026-03-09
## Description
The file upload API endpoint returns HTTP 500 when uploading files larger than approximately 10MB. Smaller files upload successfully.
## Steps to Reproduce
1. Log into the application with any valid account
2. Navigate to the Upload section
3. Select a file larger than 10MB (tested with 15MB PNG and 25MB PDF)
4. Click "Upload"
5. Observe HTTP 500 response
## Expected Behavior
File uploads successfully and appears in the user's file list.
## Actual Behavior
Server returns HTTP 500 Internal Server Error. No file is saved. No meaningful error message returned to the client.
## Environment
- Browser: Chrome 122 / Firefox 123
- OS: Windows 11, macOS 14
- API Version: v2.3.1
- Server: Production (us-east-1)
## Investigation Suggestions
- Check server logs for the specific exception/stack trace
- Verify upload size limits in nginx/reverse proxy config
- Check application-level file size validation
- Review multipart parsing library for memory limits
- Check disk space on upload volume
- Test with different file types to isolate (is it size or content type?)
## Related Patterns
Large file upload failures commonly caused by:
- Reverse proxy body size limits (nginx: `client_max_body_size`)
- Application framework limits (Express: `bodyParser.json({limit})`)
- Memory exhaustion during multipart parsing
- Request timeout before upload completes
GitHub Issue Template Output (--template github):
Outputs with GitHub-compatible labels and formatting ready for gh issue create.
1---2name: bug-report3description: Generate structured, actionable bug reports from rough descriptions — with reproduction steps, expected vs actual behavior, severity classification, and suggested investigation areas.4---56# Bug Report78Turn "it's broken" into a proper bug report. Structured, actionable, developer-ready.910## What It Does1112Takes a rough bug description and generates:13- **Title** (concise, searchable)14- **Reproduction steps** (numbered, specific)15- **Expected vs actual behavior**16- **Severity and priority** classification17- **Environment details** template18- **Suggested investigation areas**19- **Related patterns** (common causes for this type of bug)2021## Usage2223### From description:24```25bug-report "login page crashes when I use special characters in password"26```2728### With context:29```30bug-report "API returns 500 on large file uploads" --component "upload-service" --env "production" --frequency "always"31```3233### Options:34- `--component` — affected component/service35- `--env` — environment where it occurs: `production`, `staging`, `development`, `local`36- `--frequency` — `always`, `intermittent`, `once`, `unknown`37- `--user-impact` — `blocking`, `major`, `minor`, `cosmetic`38- `--format` — `markdown` (default), `json`, `github` (GitHub issue template)39- `--template` — `standard` (default), `jira`, `linear`, `github`4041## Generation Rules4243### Title:44- Under 80 characters45- Pattern: `[Component] Short description of the defect`46- Include the failing action and the symptom47- Good: "Login page crashes with special characters in password field"48- Bad: "Bug in login" or "Page doesn't work"4950### Reproduction Steps:511. Start with preconditions (logged in/out, specific data state)522. Number each step533. Be specific ("Click the Submit button" not "Submit the form")544. Include exact input data where relevant555. End with the step that triggers the bug5657### Severity Classification:5859| Severity | Criteria | Examples |60|----------|----------|---------|61| **Critical** | System crash, data loss, security vulnerability, no workaround | App crashes on launch, data corruption, auth bypass |62| **High** | Major feature broken, significant user impact, workaround exists but painful | Can't upload files (core feature), slow response (>30s) |63| **Medium** | Feature partially broken, workaround available, moderate impact | Sort order wrong, pagination off by one |64| **Low** | Minor inconvenience, cosmetic, rarely encountered | Typo in error message, alignment issue, tooltip wrong |6566### Priority (separate from severity):6768| Priority | When to Fix |69|----------|------------|70| P0 | Immediately (production down, security breach) |71| P1 | This sprint / within 48 hours |72| P2 | Next sprint / within 2 weeks |73| P3 | Backlog / when convenient |7475### Investigation Suggestions:76Based on the bug type, suggest where to look:7778| Bug Pattern | Investigation Areas |79|-------------|-------------------|80| Crash on input | Input validation, character encoding, buffer limits |81| 500 error | Server logs, exception handler, request payload size |82| Intermittent failure | Race conditions, caching, timeouts, connection pooling |83| Wrong data | Query logic, data transformation, timezone handling |84| UI glitch | CSS specificity, viewport handling, browser compatibility |85| Performance | Database queries, N+1 problems, memory leaks, missing indexes |86| Auth issues | Token expiry, session handling, CORS, cookie domain |8788### Output (Markdown):8990```markdown91# [Upload Service] API returns 500 on large file uploads9293**Severity:** High | **Priority:** P1 | **Component:** upload-service94**Environment:** Production | **Frequency:** Always95**Reported:** 2026-03-099697## Description98The file upload API endpoint returns HTTP 500 when uploading files larger than approximately 10MB. Smaller files upload successfully.99100## Steps to Reproduce1011. Log into the application with any valid account1022. Navigate to the Upload section1033. Select a file larger than 10MB (tested with 15MB PNG and 25MB PDF)1044. Click "Upload"1055. Observe HTTP 500 response106107## Expected Behavior108File uploads successfully and appears in the user's file list.109110## Actual Behavior111Server returns HTTP 500 Internal Server Error. No file is saved. No meaningful error message returned to the client.112113## Environment114- Browser: Chrome 122 / Firefox 123115- OS: Windows 11, macOS 14116- API Version: v2.3.1117- Server: Production (us-east-1)118119## Investigation Suggestions120- Check server logs for the specific exception/stack trace121- Verify upload size limits in nginx/reverse proxy config122- Check application-level file size validation123- Review multipart parsing library for memory limits124- Check disk space on upload volume125- Test with different file types to isolate (is it size or content type?)126127## Related Patterns128Large file upload failures commonly caused by:129- Reverse proxy body size limits (nginx: `client_max_body_size`)130- Application framework limits (Express: `bodyParser.json({limit})`)131- Memory exhaustion during multipart parsing132- Request timeout before upload completes133```134135### GitHub Issue Template Output (--template github):136Outputs with GitHub-compatible labels and formatting ready for `gh issue create`.
dvcrn