Writing Issues

Category: Development & Coding | Uploader: notorious-ai | Downloads: 0 | Version: v1.0（Latest）
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.
Changelog: Source: GitHub https://github.com/notorious-ai/claude-plugins
Directory Structure

Current level: github-author/skills/writing-issues/
📁 examples/
- 📄 bad-issue-examples.md 8.1 KB
- 📄 good-issue-examples.md 14.8 KB
📁 references/
- 📄 body-structure.md 7.0 KB
📄 SKILL.md 10.3 KB
SKILL.md

---
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:

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**:
```markdown
- [ ] Add database column
- [ ] Update API endpoint
- [ ] Modify frontend form
```

**Prefer**:
```markdown
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**:

```markdown
## 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

<negative>
<pattern>Prescribing implementation steps instead of outcomes</pattern>
<reason>Issues define what needs to happen, not how. "Add a database column" prescribes; "Users need to specify timezone" describes outcome.</reason>
</negative>

<negative>
<pattern>Using imperative titles: "Add timezone support", "Fix search crash"</pattern>
<reason>Imperative mood suits PRs (commands that execute). Issues use present progressive to indicate ongoing work: "Supporting timezone preferences".</reason>
</negative>

<negative>
<pattern>Skipping the "why does this matter" opening</pattern>
<reason>The opening paragraph must establish motivation. Without it, readers don't know why they should care about this issue.</reason>
</negative>

<negative>
<pattern>Creating task-like issues for small items: "Update button color"</pattern>
<reason>Small tasks belong in parent issue checklists, not standalone issues. Issues track meaningful work with clear outcomes.</reason>
</negative>

<negative>
<pattern>Framing missing features as bugs: "Bug: no dark mode"</pattern>
<reason>Missing functionality is a feature request, not a bug. Bugs describe incorrect behavior; features describe new capability.</reason>
</negative>

## 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
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
Writing Issues

Directory Structure

SKILL.md

Report

Notice
