gmacko-dev-issue-create

name	gmacko-dev-issue-create
description	Use when (1) creating GitHub issues from feature plans or bug reports, (2) documenting bugs found during development, (3) managing the project backlog. Creates well-structured GitHub issues with templates and labels.
license	MIT
compatibility	opencode
metadata	{"phase":"development","tier":"workhorse","permission":"ask"}

Gmacko Issue Creator

Create well-structured GitHub issues using the gh CLI with proper templates, labels, and linking.

Prerequisites

• gh CLI installed and authenticated
• Repository exists on GitHub (gmacko org)
• Issue templates in .github/ISSUE_TEMPLATE/

Workflow

digraph issue_create {
    rankdir=TB;
    node [shape=box];
    
    start [label="Start" shape=ellipse];
    type [label="1. Determine Issue Type"];
    gather [label="2. Gather Information"];
    validate [label="3. Validate Requirements"];
    valid [label="Valid?" shape=diamond];
    preview [label="4. Preview Issue"];
    confirm [label="5. Confirm Creation"];
    approved [label="Approved?" shape=diamond];
    create [label="6. Create Issue via gh"];
    link [label="7. Link to Plan"];
    done [label="Issue Created" shape=ellipse];
    fix [label="Revise"];
    
    start -> type -> gather -> validate -> valid;
    valid -> preview [label="yes"];
    valid -> fix [label="no"];
    fix -> gather;
    preview -> confirm -> approved;
    approved -> create [label="yes"];
    approved -> fix [label="no"];
    create -> link -> done;
}

Issue Types & Templates

Bug Report

Use .github/ISSUE_TEMPLATE/bug.yml:

• Title prefix: [Bug]:
• Required: description, reproduction steps, expected/actual behavior
• Labels: type:bug, status:needs-triage

Feature Request

Use .github/ISSUE_TEMPLATE/feature.yml:

• Title prefix: [Feature]:
• Required: problem statement, proposed solution, acceptance criteria
• Labels: type:feature, status:needs-triage

Task (from feature plan)

Custom format:

• Title prefix: [Task]:
• Parent issue reference
• Labels: type:task, appropriate area label

Label Taxonomy

Type Labels

• type:bug - Something isn't working
• type:feature - New functionality
• type:task - Implementation task
• type:docs - Documentation
• type:chore - Maintenance/tooling

Status Labels

• status:needs-triage - Needs review
• status:ready - Ready for implementation
• status:in-progress - Being worked on
• status:blocked - Waiting on dependency
• status:needs-review - PR submitted

Area Labels

• area:web - Next.js app
• area:mobile - Expo app
• area:api - tRPC routers
• area:db - Database/schema
• area:shared - Shared packages

Priority Labels

• priority:critical - Blocking users
• priority:high - Significant impact
• priority:medium - Normal priority
• priority:low - Nice to have

Execution Steps

Step 1: Determine Issue Type

Ask:

What type of issue should I create?

1. Bug report
2. Feature request
3. Task (from existing plan)
4. Documentation update

Step 2: Gather Information

For Bugs:

REQUIRED INFORMATION
====================
1. Title (concise description)
2. Bug description
3. Steps to reproduce
4. Expected behavior
5. Actual behavior
6. Platform(s) affected
7. Environment (dev/staging/prod)
8. Error logs (if any)
9. Sentry link (if any)

For Features:

REQUIRED INFORMATION
====================
1. Title (feature name)
2. Problem statement (what problem does it solve?)
3. Proposed solution
4. Acceptance criteria (testable conditions)
5. Platform(s) affected
6. Priority suggestion
7. Link to INITIAL_PLAN.md section (if applicable)
8. Mockups/screenshots (if any)

For Tasks:

REQUIRED INFORMATION
====================
1. Title (task description)
2. Parent issue/feature
3. Detailed description
4. Acceptance criteria
5. Area (web/mobile/api/db)
6. Estimated effort
7. Dependencies

Step 3: Validate Requirements

Ensure all required fields are complete:

VALIDATION CHECKLIST
====================
[OK] Title is descriptive (5-50 chars)
[OK] Problem/description is clear
[OK] Acceptance criteria defined
[OK] Platform(s) specified
[MISSING] Steps to reproduce (required for bugs)

If missing required fields, ask for them.

Step 4: Preview Issue

Show the user what will be created:

ISSUE PREVIEW
=============

**Title**: [Bug]: Login button unresponsive on mobile

**Labels**: type:bug, area:mobile, priority:high, status:needs-triage

**Body**:
## Bug Description
The login button on the sign-in screen doesn't respond to taps...

## Steps to Reproduce
1. Open the app
2. Navigate to sign-in
3. Tap the login button
4. Nothing happens

## Expected Behavior
Button should trigger authentication flow

## Actual Behavior
No response, no error

## Platform
- Mobile iOS (Expo)

## Environment
- Production

## Error Logs
No errors in console

---

Does this look correct?

Step 5: Confirm Creation

IMPORTANT: Creating issues is an external side effect. Always confirm.

I'm about to create this issue on GitHub.

Repository: gmacko/[project-name] Title: [Bug]: Login button unresponsive on mobile Labels: type:bug, area:mobile, priority:high

Proceed? (yes/no)

Step 6: Create Issue via gh

Execute the gh command:

# For bug reports
gh issue create \
  --title "[Bug]: Login button unresponsive on mobile" \
  --label "type:bug,area:mobile,priority:high,status:needs-triage" \
  --body-file /tmp/issue-body.md

# For features
gh issue create \
  --title "[Feature]: Add dark mode support" \
  --label "type:feature,area:web,area:mobile,priority:medium,status:needs-triage" \
  --body-file /tmp/issue-body.md

# For tasks with parent
gh issue create \
  --title "[Task]: Implement dark mode toggle component" \
  --label "type:task,area:web,status:needs-triage" \
  --body "Parent: #123

## Description
Create the dark mode toggle component...

## Acceptance Criteria
- [ ] Toggle switches theme
- [ ] Preference persisted
"

Step 7: Link to Plan (if applicable)

If this issue relates to a feature plan:

1. Update the plan document to reference the issue
2. Add issue link to docs/ai/handoffs/{feature}-plan.md

## Related Issues
- #456 - Main feature issue
- #457 - Database task
- #458 - API task
- #459 - UI task

Report success:

Issue created successfully!

URL: https://github.com/gmacko/[project]/issues/456 Number: #456

Next steps:

• Add to project board (if using)
• Assign to developer
• Link related issues

Batch Creation

For creating multiple issues from a feature plan:

BATCH CREATION
==============
Creating issues for feature: Dark Mode Support

1. [Feature]: Dark mode support - Epic
2. [Task]: Database schema for theme preferences - #457
3. [Task]: API endpoint for theme settings - #458
4. [Task]: Web theme toggle component - #459
5. [Task]: Mobile theme toggle screen - #460

All issues created and linked to parent #456.

Red Flags

Rationalization	Correction
"I'll create without confirmation"	ALWAYS confirm before gh issue create
"Labels aren't important"	Proper labels enable filtering and triage
"No need for acceptance criteria"	Criteria required for QA verification
"I'll link the plan later"	Link immediately for traceability

Error Handling

gh not authenticated

gh auth login

Repository not found

gh repo view gmacko/[project-name]
# If missing, create first:
gh repo create gmacko/[project-name] --private

Label doesn't exist

# Create missing labels
gh label create "type:bug" --color "d73a4a" --description "Something isn't working"
gh label create "type:feature" --color "a2eeef" --description "New feature or request"

Dependencies

• Requires: gh CLI authenticated
• Input: Bug report, feature request, or task description
• Output: GitHub issue URL
• Related: gmacko-dev-feature-plan (provides task breakdown)