github-issue

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

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

Issue Templates

Bug Template (matches .github/ISSUE_TEMPLATE/bug_report.yaml)

Title format: fix: <description>

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

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

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

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

Workflow

1. Gather Information: Ask clarifying questions to understand the issue
2. Determine Type: Based on scope, choose Epic/Feature/Task/Bug
3. Search for Parent: Search for related Features/Epics and ask user which to link
4. Draft Issue: Use the appropriate template matching .github/ISSUE_TEMPLATE/
5. Review with User: Show the draft before creating
6. Create Issue: 3-step process below

Creating Issues (3-step process)

Step 1: Create the issue

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

# 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

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

gh issue list --search "related keywords" --limit 10

Best Practices

1. Use correct title prefix: fix:, feat:, task:, epic:

2. One issue, one concern: Don't combine multiple bugs or features

3. Use sub-issue API for hierarchy: Never use "Part of #XXX" text, use GraphQL addSubIssue

4. Include context: Explain why, not just what

5. Be specific: Include file paths, error messages, steps to reproduce

6. Match existing templates: Follow the structure from .github/ISSUE_TEMPLATE/

Example: Creating a Bug

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
)"