issue-writing

name	issue-writing
description	Write clear, actionable bug reports and feature requests that humans and agents can act on immediately

Issue Writing

Write structured issue tickets — bug reports, feature requests, and task descriptions — that contain all the information needed for immediate action.

Deep guide: This skill is standalone. For related patterns see Documentation Guidelines and PRD for Agents.

Triggers

Use this skill when you need to:

• File a bug report for a defect you discovered
• Write a feature request based on user feedback or product need
• Break down a large task into sub-issues
• Document a technical debt item for future work
• Create a spike/investigation ticket

Process

1. Choose the Issue Type

Type	Template	When
Bug Report	Bug Template	Something is broken or behaves unexpectedly
Feature Request	Feature Template	New capability or enhancement needed
Task	Task Template	Work item that needs to be completed
Spike	Spike Template	Investigation or research needed before implementation

2. Write a Clear Title

Pattern	Example
[Component] Verb + specific context	[Auth] Login fails when email contains '+' character
[Area] Expected vs actual	[API] GET /users returns 500 instead of 404 for missing user
Avoid vague titles	❌ "Bug in login" ❌ "Fix issue" ❌ "Something broken"

3. Fill in the Template

Follow the appropriate template below. Every field exists for a reason — incomplete issues waste time.

4. Add Context

• Attach screenshots, logs, or stack traces
• Link to related issues, PRs, or discussions
• Tag affected components or areas
• Set priority based on impact and urgency

5. Review Before Submitting

Check	Why
Could someone act on this without asking questions?	Self-contained issues save roundtrips
Is the title scannable in a list?	Teams triage by title first
Are reproduction steps numbered and specific?	Vague steps like "login and try stuff" are useless
Is expected vs actual behavior explicit?	Without both, you're describing a symptom, not a bug

Bug Report Template

## Bug: [Component] Brief description

### Environment
- OS / Browser: 
- Version / Commit: 
- Environment: staging / production / local

### Steps to Reproduce
1. Navigate to ...
2. Click on ...
3. Enter "..." in the field
4. Submit the form

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happens]

### Error Output
[Stack trace, console errors, or log output]

### Severity
- [ ] Critical — system down, data loss
- [ ] High — feature broken, no workaround
- [ ] Medium — feature broken, workaround exists
- [ ] Low — cosmetic or minor inconvenience

Feature Request Template

## Feature: [Area] Brief description

### Problem
[What pain point or need does this address?]

### Proposed Solution
[What should be built? Be specific about behavior.]

### Acceptance Criteria
- [ ] [Criterion 1 — testable, specific]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

### Alternatives Considered
[What other approaches were considered and why they were rejected?]

### Impact
- Users affected: [scope]
- Priority: [high / medium / low]

Task Template

## Task: [Area] Brief description

### Goal
[One sentence — what does completing this achieve?]

### Requirements
- [ ] [Specific deliverable 1]
- [ ] [Specific deliverable 2]
- [ ] [Specific deliverable 3]

### Dependencies
[What must be done before this? Link to blocking issues.]

### Definition of Done
[How do we know this is complete? Tests pass? Docs updated? PR merged?]

Spike Template

## Spike: [Area] Brief description

### Question
[What specific question needs answering?]

### Context
[Why do we need to investigate this? What decision depends on the answer?]

### Time Box
[Maximum time to spend — e.g., "4 hours" or "1 day"]

### Expected Output
[What deliverable comes from this spike? Decision doc? Prototype? Recommendation?]

Red Flags

Signal	Action	Rationale
Title is vague ("Fix bug", "Update thing")	Rewrite with component + specific context	Vague titles get deprioritized and misunderstood
No reproduction steps on a bug report	Add numbered, specific steps	Unreproducible bugs don't get fixed
Issue mixes multiple unrelated problems	Split into separate issues	Multi-problem issues get partially completed and forgotten
No acceptance criteria on a feature request	Add testable criteria	Without criteria, "done" is undefined
Issue has been open for 30+ days with no activity	Re-evaluate priority or close	Stale issues clutter the backlog

Related Skills

Skill	When to Chain
Planning	Break large issues into planned implementation steps
PR Writing	Reference the issue in your PR for traceability
Doc Maintenance	Update docs when closing feature issues