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:

gh issue create --title "Brief descriptive title" --body "$(cat <<'EOF'
## Summary
<1-3 sentences describing what needs to be done>

## Current State
<What exists now, with file paths and code references>

## Proposed Changes
<What should change, with specific details>

## Technical Notes
<File paths, database tables, API endpoints, code snippets>

## Acceptance Criteria
- [ ] Specific testable requirement
- [ ] Another requirement
EOF
)"

Step 3: Add Labels

Discover current labels and apply appropriate ones:

gh 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

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

Step 4: Add to Project (if applicable)

If the repository uses GitHub Projects:

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

Issue Template

## Summary
<1-3 sentences describing what needs to be done>

## Current State
<What exists now>
- File: `path/to/file.ts:123`
- Current behavior: <description>

## Proposed Changes
<What should change>
1. Change X to do Y
2. Add Z functionality

## Technical Notes
- Relevant files: `src/components/Feature.tsx`, `src/utils/helpers.ts`
- Related functions: `handleSubmit()`, `validateInput()`
- Consider: <architectural notes, edge cases>

## Acceptance Criteria
- [ ] Specific testable requirement
- [ ] Another requirement
- [ ] Tests pass

## Additional Context
<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

| Mistake | Fix | |---------|-----| | Create issue without researching code first | Use Explore agent to find relevant files | | Generic issue description | Include specific file paths, line numbers, code snippets | | Missing acceptance criteria | Always include testable requirements | | No labels | Always add at least a type label | | Vague title | Make titles specific and searchable |