| name | Writing Issues |
| description | Encodes GitHub issue authoring conventions including present-progressive titles, outcome-focused bodies, problem-space framing, and definition-of-done patterns. Must be loaded before composing any issue title or body, whether drafting interactively or creating programmatically with gh issue create. |
| user-invocable | false |
Writing Issues
Effective issues focus on the why over the how. They describe desired outcomes rather than prescribing implementation steps. The issue author specifies what needs to happen; the assignee determines how to accomplish it.
Core Principle: Ongoing Efforts
Issues track ongoing work. The title reflects this with present progressive verbs - work that is happening, not a command to execute.
Think: "This issue is _____ (verb+ing)"
| Imperative (avoid) | Present Progressive (prefer) |
|---|
| Add timezone support | Supporting user timezone preferences |
| Fix search crash | Fixing search crash on large date ranges |
| Implement caching | Improving response times for frequent queries |
| Remove deprecated API | Removing legacy v1 API endpoints |
The imperative mood suits PRs (commands that execute on merge). Present progressive suits issues (work in progress).
Title Structure
Issue titles use present progressive, beginning with a meaningful verb:
Format: <Verb+ing> <what is being accomplished>
- Begin with present progressive verb (-ing form)
- Describe the goal or outcome being worked toward
- Keep concise but descriptive
- Avoid labels in the title (use GitHub labels instead)
Examples by type:
- Feature:
Supporting user timezone preferences
- Bug:
Fixing search crash on large date ranges
- Task:
Migrating authentication to passport-next
- Investigation:
Investigating duplicate order submissions
- Discussion:
Evaluating GraphQL migration for public API
Gathering Context
Before drafting an issue, gather context:
From the Conversation
Draw from the discussion that surfaced the need:
- What problem or need was identified?
- Who is affected and how?
- What constraints exist?
- What outcome would resolve this?
When context is incomplete, ask proactively. The motivation behind an issue is essential for effective tracking.
Surfacing Hidden Context
Issues live in the problem-space: they define what needs solving without prescribing how. The body must surface the context that makes the problem clear and the outcome verifiable.
What the Prose Must Capture
Issues describe what the diff cannot convey (because the diff doesn't exist yet). The body must explain:
- Who is affected: Which users, systems, or processes experience this problem
- How they are affected: The specific pain, limitation, or risk
- Impact if unaddressed: What happens if this issue is never resolved
- What outcome would resolve this: The verifiable end state (see "Definition of Done")
- Constraints limiting solutions: Technical, organizational, or timeline boundaries
- Scope boundaries: What is explicitly not part of this issue's definition of done
- Related prior attempts: What has been tried before and why it didn't work (brief context, not exhaustive history)
Detecting Missing Context
Use intelligence to detect when essential context is missing. When gaps exist, ask targeted questions before drafting:
- "Who specifically encounters this problem and in what situation?"
- "What happens to them if this remains unaddressed?"
- "What would 'done' look like - what should be true when this is resolved?"
If the user cannot provide the information after being asked, insert actionable placeholders that specify exactly what information is missing and how to obtain it:
[FILL: Interview support team for frequency of this complaint][FILL: Check analytics for user journey drop-off data][FILL: Ask product owner for priority relative to roadmap]
Placeholders must be specific enough that someone can act on them immediately.
From the Repository
Check for existing context:
- Search open issues for related or duplicate work
- Review recently closed issues for prior attempts
- Check for issue templates in
.github/ISSUE_TEMPLATE/
Use gh issue list to discover related work. Reference relevant issues to connect efforts.
Body Philosophy
Issues are problem-space documents. They define what needs solving and why it matters. PRs (solution-space) explain how; issues explain why.
The body explains why this issue exists and what outcome is needed. Leave the how to the assignee. Implementation prescription removes agency from the person doing the work and often misses better approaches.
The first paragraph immediately follows the title without a header. This opening establishes context and motivation - the "why does this matter" that pulls readers in.
Prose Over Checklists
Describe goals and constraints as prose. Avoid prescriptive task lists:
Avoid:
- [ ] Add database column
- [ ] Update API endpoint
- [ ] Modify frontend form
Prefer:
User profiles lack timezone information, causing scheduled notifications
to arrive at inconvenient times. Users should be able to specify their
timezone so notifications respect their local time.
The first prescribes implementation. The second describes the outcome.
When Checklists Are Appropriate
Checklists suit tracking scope or acceptance criteria as outcomes:
## Acceptance Criteria
- [ ] Users can specify timezone in profile settings
- [ ] Scheduled notifications respect user timezone
- [ ] Default timezone inferred from browser when not set
These are outcomes to achieve, not steps to implement.
Definition of Done
Include a clear outcome statement. The pattern "By the time this Issue is complete, the system will have..." works well for defining scope and completion criteria.
Examples:
- "By the time this Issue is complete, users will be able to specify their timezone so notifications respect their local time."
- "By the time this Issue is complete, the API will validate all input before processing."
This framing forces clarity about what "done" means and helps prevent scope creep.
Issue Templates
Before creating an issue, check for templates in .github/ISSUE_TEMPLATE/. Templates encode repository-specific conventions. When a template applies to the issue type, follow its structure.
Type-Specific Guidance
While uniform principles apply to all issues, certain types benefit from specific context. Consult references/body-structure.md for detailed guidance on:
- Bug reports: Environment, reproduction steps, expected vs actual behavior
- Feature requests: User impact, success criteria
- Discussion issues: Decision framing, questions to consider
Follow-up Tasks
When an issue identifies post-completion work, list it clearly at the end. See references/body-structure.md for formatting.
Workflow
When creating an issue:
- Gather context: Understand the problem, who is affected, and desired outcome
- Search for related work: Check open/closed issues for duplicates or related efforts
- Check templates: Use repository templates when applicable
- Draft title: Present progressive verb + goal (not imperative)
- Write body: Focus on why and what, link related work
- Review: Does the title reflect ongoing work? Does the body describe outcome over implementation?
Reference Files
For detailed guidance, consult:
| File | Contains |
|---|
references/body-structure.md | Body format, prose flow, type specializations, linking related resources |
examples/good-issue-examples.md | Effective issue examples with probe tags showing context discovery |
examples/bad-issue-examples.md | Anti-patterns with detailed rationale for why they fail |
About probe tags: Example files use <probe> tags to demonstrate targeted questions that surface essential context. Each probe shows what to ask ("Who is affected?", "What's the impact?") and the information it reveals. Use this pattern when gathering context before drafting.
What to Avoid
Prescribing implementation steps instead of outcomes
Issues define what needs to happen, not how. "Add a database column" prescribes; "Users need to specify timezone" describes outcome.
Using imperative titles: "Add timezone support", "Fix search crash"
Imperative mood suits PRs (commands that execute). Issues use present progressive to indicate ongoing work: "Supporting timezone preferences".
Skipping the "why does this matter" opening
The opening paragraph must establish motivation. Without it, readers don't know why they should care about this issue.
Creating task-like issues for small items: "Update button color"
Small tasks belong in parent issue checklists, not standalone issues. Issues track meaningful work with clear outcomes.
Framing missing features as bugs: "Bug: no dark mode"
Missing functionality is a feature request, not a bug. Bugs describe incorrect behavior; features describe new capability.
Line Formatting for GitHub
GitHub's markdown renderer treats hard newlines within a paragraph as literal line breaks. When composing --body content for gh issue create, write each paragraph as a single continuous line with no mid-sentence wraps. Newlines should only appear:
- Between paragraphs (blank line)
- Before list items, headings, or code blocks
- Where markdown syntax requires them
This differs from git commit -m, where hard wraps are conventional because terminals render them directly.
Validation Checklist
Before presenting the issue:
Title:
Body:
