GitHub Issue Creation Skill
Purpose
Help create well-structured GitHub issues that follow the project's hierarchy,
conventions, and existing templates from .github/ISSUE_TEMPLATE/.
Issue Hierarchy
code
Epic (large initiative, multiple features)
└── Feature (user-facing capability, multiple tasks)
└── Task (single unit of work)
└── Bug (defect to fix)
When to Use Each Type
| Type | Title Prefix | Use When |
|---|---|---|
| Epic | epic: | Large initiative spanning weeks/months |
| Feature | feat: | New user-facing capability |
| Task | task: | Single unit of implementation work |
| Bug | fix: | Something is broken/not working as expected |
Issue Templates
Bug Template (matches .github/ISSUE_TEMPLATE/bug_report.yaml)
Title format: fix: <description>
markdown
## Summary [One sentence about what's broken] ## Environment - App version: [e.g., 1.2.3] - Device: [e.g., iPhone 14 Pro, iOS 17.1] - Network: [WiFi / Cellular] ## Steps to Reproduce 1. Go to '...' 2. Click on '...' 3. See error ## Actual Result [What actually happened] ## Expected Result [What you expected to happen] ## Regression? [Yes / No / Unknown - Did this work in a previous version?] ## Evidence [Screenshots, screen recordings, logs, crash reports]
Feature Template (matches .github/ISSUE_TEMPLATE/feature_request.yaml)
Title format: feat: <description>
markdown
## What would you like? [Describe the feature or improvement] ## How would this be useful for you? [What problem does this solve or what does it make easier?] ## When would you use this? [Describe a situation where you'd need this feature] ## Anything else? [Screenshots, mockups, examples from other apps]
Task Template
Title format: task: <description>
markdown
## Description [Clear description of what needs to be done] ## Context [Why this task is needed] ## Implementation Notes [Technical approach, files to modify, considerations] ## Acceptance Criteria - [ ] Criterion 1 - [ ] Criterion 2 ## Testing [How to verify this task is complete]
Epic Template
Title format: epic: <description>
markdown
## Overview [High-level description of the initiative] ## Goals - [ ] Goal 1 - [ ] Goal 2 ## Features - [ ] #XXX Feature name - [ ] #YYY Feature name ## Success Criteria [How we know this epic is complete] ## Notes [Additional context, constraints, or considerations]
Relationships
Use GitHub's sub-issue API (NOT text like "Part of #123" in the body):
| Relationship | How |
|---|---|
| Parent/Child | addSubIssue GraphQL mutation |
| Related | Related to #789 in body text |
| Blocks | Blocks #101 in body text |
| Blocked by | Blocked by #102 in body text |
Workflow
- •Gather Information: Ask clarifying questions to understand the issue
- •Determine Type: Based on scope, choose Epic/Feature/Task/Bug
- •Search for Parent: Search for related Features/Epics and ask user which to link
- •Draft Issue: Use the appropriate template matching
.github/ISSUE_TEMPLATE/ - •Review with User: Show the draft before creating
- •Create Issue: 3-step process below
Creating Issues (3-step process)
Step 1: Create the issue
bash
gh issue create \ --title "fix:|feat:|task:|epic: Description" \ --body "..." \ --assignee NotThatKindOfDrLiz
Step 2: Set issue type via GraphQL
Available types and their IDs (repo: divinevideo/divine-mobile):
- •Task:
IT_kwDODpf9Q84ByDOD - •Bug:
IT_kwDODpf9Q84ByDOE - •Feature:
IT_kwDODpf9Q84ByDOF
bash
# Get the issue node ID
gh api graphql -f query='{ repository(owner: "divinevideo", name: "divine-mobile") {
issue(number: ISSUE_NUMBER) { id }
} }'
# Set the type
gh api graphql -f query='mutation { updateIssueIssueType(input: {
issueId: "ISSUE_NODE_ID",
issueTypeId: "TYPE_ID"
}) { issue { id } } }'
Step 3: Set parent relationship via GraphQL
bash
# Get parent issue node ID
gh api graphql -f query='{ repository(owner: "divinevideo", name: "divine-mobile") {
issue(number: PARENT_NUMBER) { id }
} }'
# Add as sub-issue
gh api graphql -f query='mutation { addSubIssue(input: {
issueId: "PARENT_NODE_ID",
subIssueId: "CHILD_NODE_ID"
}) { issue { id } subIssue { id } } }'
Search for Parent Issues
Before creating a Task or Bug, search for related Features/Epics:
bash
gh issue list --search "related keywords" --limit 10
Best Practices
- •
Use correct title prefix:
fix:,feat:,task:,epic: - •
One issue, one concern: Don't combine multiple bugs or features
- •
Use sub-issue API for hierarchy: Never use "Part of #XXX" text, use GraphQL
addSubIssue - •
Include context: Explain why, not just what
- •
Be specific: Include file paths, error messages, steps to reproduce
- •
Match existing templates: Follow the structure from
.github/ISSUE_TEMPLATE/
Example: Creating a Bug
bash
gh issue create \
--title "fix: Profile stats labels wrap incorrectly on small screens" \
--body "$(cat <<'EOF'
## Summary
Profile stats labels ("Followers", "Following") wrap to multiple lines, splitting words mid-word.
## Environment
- App version: Latest
- Device: Small screen devices
- Network: N/A
## Steps to Reproduce
1. Open profile screen on a small device or narrow width
2. Look at the stats row (Videos, Followers, Following)
3. See labels wrapping incorrectly
## Actual Result
Labels wrap mid-word:
- "Followers" becomes "Follower" + "s"
- "Following" becomes "Followin" + "g"
## Expected Result
Labels should remain on a single line, or truncate with ellipsis if needed.
## Regression?
Unknown
## Evidence
<!-- Screenshot to be attached after creation -->
EOF
)"