Writing Issues

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:

1. What problem or need was identified?
2. Who is affected and how?
3. What constraints exist?
4. 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:

1. Search open issues for related or duplicate work
2. Review recently closed issues for prior attempts
3. 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:

1. Gather context: Understand the problem, who is affected, and desired outcome
2. Search for related work: Check open/closed issues for duplicates or related efforts
3. Check templates: Use repository templates when applicable
4. Draft title: Present progressive verb + goal (not imperative)
5. Write body: Focus on why and what, link related work
6. 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:

• Uses present progressive verb (-ing form)
• Describes goal or outcome, not developer action
• Avoids labels or type prefixes (use GitHub labels)

Body:

• Opens with untitled paragraph explaining why
• Focuses on desired outcome, not implementation steps
• Links related issues using full short syntax (org/repo#123)
• Uses checklists for scope/criteria, not implementation steps
• Follows repository template when applicable