Investigate a bug or define requirements for a feature, then produce a structured issue document. Use when the user asks to "create an issue", "write a ticket", "investigate a bug", "define a feature", or needs a well-structured problem statement for their tracker.
As a Staff Software Engineer, investigate the provided error, bug report, or feature request and produce a well-defined issue document. Focus on thoroughly understanding and documenting the problem - solution planning comes later.
Your goal: Create an issue so clear that any developer could understand the problem completely and then plan a solution.
Understand the problem before documenting it:
# [Descriptive Title]
Specific title describing the problem (not the solution).
Bad: "Fix login" | Good: "Login fails silently when SSO session expires mid-authentication"
## Summary
2-3 sentences: What's the problem, who's affected, and why does it matter?
## Problem Description
### Current Behavior
- Observable symptoms
- Error messages or logs (quote relevant excerpts)
- Reproduction steps (for bugs)
- Root cause, if identified
### Expected Behavior
What should happen instead. Be specific.
### Impact
- Who is affected (users, systems, teams)
- Severity (data loss, degraded experience, inconvenience)
- Frequency (constant, intermittent, edge case)
## Context
What a developer needs to understand this problem:
- Relevant code: `[filename.ext:line](path#Lline)`
- Architecture or system components involved
- Dependencies or integrations
- Key constraints
## Scope
### This Issue Addresses
- Specific problem(s) to solve
- Clear boundaries
### Out of Scope
- Related concerns for separate issues
## Acceptance Criteria
How we know this is done:
- [ ] Specific, testable criterion
- [ ] Another measurable outcome
- [ ] Relevant tests pass
Keep criteria focused on **outcomes**, not implementation details.
## Additional Context
- Related issues or PRs
- Customer reports or support tickets
- Screenshots, logs, or examples
---
**Signals:**
- Severity: [Low | Medium | High | Critical]
- Complexity Estimate: [Small | Medium | Large | XL]
Before finalizing:
Focus on the problem. Define what needs solving and why.
Capture context. Include enough detail that someone unfamiliar can understand without asking questions.
Be evidence-driven. Reference specific code, quote actual errors, cite real data.
Scope ruthlessly. A focused issue gets solved. A sprawling issue becomes backlog.
Save as issue-brief-problem-description.md in the appropriate location (project root, .github/issues/, or as specified).