Creating GitHub Issues

Overview

Every GitHub issue should be well-researched and clearly documented. This skill ensures issues contain enough context for anyone to understand and implement them.

Mandatory Workflow

Step 1: Research the Codebase

Before writing the issue, use the Explore agent or search tools to understand:

• Where relevant code lives (file paths, functions, components)
• How similar functionality is currently implemented
• Database tables, API endpoints, or UI components involved
• Existing patterns that should be followed

Include in the issue:

• Specific file paths and line numbers
• Code snippets showing current implementation
• References to similar existing code as examples

Why: Issues with research reduce back-and-forth questions and give implementers a head start.

Step 2: Create the Issue

Use gh issue create with a well-structured body:

bash
1gh issue create --title "Brief descriptive title" --body "$(cat <<'EOF'
2## Summary
3<1-3 sentences describing what needs to be done>
4
5## Current State
6<What exists now, with file paths and code references>
7
8## Proposed Changes
9<What should change, with specific details>
10
11## Technical Notes
12<File paths, database tables, API endpoints, code snippets>
13
14## Acceptance Criteria
15- [ ] Specific testable requirement
16- [ ] Another requirement
17EOF
18)"

Step 3: Add Labels

Discover current labels and apply appropriate ones:

bash
1gh label list --limit 50

Common label categories:

1. Type (pick one):

   • enhancement - New feature or improvement
   • bug - Something isn't working
   • documentation - Documentation improvements
   • question - Further information requested

2. Priority (if applicable):

   • priority: critical - Production broken, blocking issue
   • priority: high - Important bug fix, urgent feature
   • priority: low - Nice to have, can wait

3. Area (if applicable):

   • Labels indicating which part of the codebase is affected

bash
1gh issue edit <number> --add-label "enhancement"

Step 4: Add to Project (if applicable)

If the repository uses GitHub Projects:

bash
1gh issue edit <number> --add-project "Project Name"

Issue Template

markdown
1## Summary
2<1-3 sentences describing what needs to be done>
3
4## Current State
5<What exists now>
6- File: `path/to/file.ts:123`
7- Current behavior: <description>
8
9## Proposed Changes
10<What should change>
111. Change X to do Y
122. Add Z functionality
13
14## Technical Notes
15- Relevant files: `src/components/Feature.tsx`, `src/utils/helpers.ts`
16- Related functions: `handleSubmit()`, `validateInput()`
17- Consider: <architectural notes, edge cases>
18
19## Acceptance Criteria
20- [ ] Specific testable requirement
21- [ ] Another requirement
22- [ ] Tests pass
23
24## Additional Context
25<Screenshots, error messages, related issues>

Field Selection Guidelines

Priority

• Critical - Production broken, blocking issue
• High - Important bug fix, urgent feature (most bugs default here)
• Medium - Standard feature work
• Low - Nice to have, can wait

Default guidance: Bugs default to High unless trivial. Enhancements default to Medium unless urgent.

Common Mistakes