Create GitHub Issue

Collaboratively plan and create well-structured GitHub issues through interactive discussion.

Input

The issue idea or problem description will be provided as: $ARGUMENTS

If no argument is provided, ask the user what they'd like to create an issue for.

Process

Step 1: Understand the Request

Parse the user's input to understand:

• •What problem they're trying to solve
• •What outcome they expect
• •Any constraints or preferences mentioned

Do NOT assume you understand the full scope. Always ask clarifying questions.

Step 2: Explore and Clarify

Use AskUserQuestion to gather information:

1. •

   Problem Context

   • •What triggered this need?
   • •Who is affected (users, developers, ops)?
   • •What's the current behavior vs. desired behavior?
2. •

   Success Criteria

   • •How will we know this is done?
   • •Are there measurable outcomes?
   • •What does "good enough" look like?
3. •

   Constraints & Dependencies

   • •Timeline considerations?
   • •Technical constraints?
   • •Dependencies on other work?

Step 3: Research the Codebase

Before proposing solutions, explore the relevant parts of the codebase:

• •Find related existing code
• •Understand current patterns and conventions
• •Identify potential integration points
• •Look for similar past implementations

Use this research to inform realistic implementation options.

Step 4: Generate Alternative Approaches

CRITICAL: Never present just one approach. Always research and present 2-4 different ways to solve the problem:

For each approach, describe:

• •Summary: One-line description
• •How it works: Brief technical explanation
• •Pros: Benefits of this approach
• •Cons: Drawbacks or risks
• •Effort estimate: Relative complexity (Low/Medium/High)
• •Files likely affected: Key areas of the codebase

Present these options to the user and discuss trade-offs. Let them choose or combine approaches.

Step 5: Assess Scope

Evaluate if this should be one issue or multiple:

Signs it should be split:

• •Multiple distinct deliverables
• •Different areas of the codebase with no overlap
• •Work that could be done in parallel by different people
• •Natural breaking points (e.g., "backend then frontend")
• •Estimated effort exceeds 1-2 days of work

Signs it should stay as one issue:

• •Tightly coupled changes
• •Single logical unit of work
• •Splitting would create coordination overhead
• •Small enough to complete in a focused session

If splitting makes sense, offer options:

1. •Single issue: Keep as-is, note it's larger
2. •Multiple issues: Create separate, linked issues
3. •Epic with sub-issues: Create a parent tracking issue with child tasks

Ask the user which structure they prefer and why.

Step 6: Draft the Issue

Issue titles MUST use conventional commit format:

<type>(<scope>): <description>

Types:

• •feat - New feature or capability
• •fix - Bug fix
• •docs - Documentation only
• •refactor - Code restructuring without behavior change
• •test - Adding or updating tests
• •chore - Maintenance, dependencies, tooling
• •perf - Performance improvement

Scope is optional but recommended - use the affected area (e.g., auth, templates, api, frontend).

Labels - Apply appropriate labels to categorize the issue:

Label Selection Guidelines:

• •Type label: Match the conventional commit type (feat→feature, fix→bug, etc.)
• •Area labels: Can apply multiple if issue spans areas (e.g., area: backend + area: frontend)
• •Discovery: For research/spike work before implementation is clear
• •Epic: For parent issues that track multiple sub-issues

Examples:

• •feat(auth): Add OAuth2 login with Google
• •fix(templates): Resolve SVG conversion timeout on large files
• •refactor(api): Migrate endpoints to new router structure
• •docs: Update API reference for v2 endpoints

Create a well-structured issue with these sections:

## Summary
[1-2 sentence description of what this issue accomplishes]

## Problem / Motivation
[Why does this need to exist? What problem does it solve? Who benefits?]

## Proposed Solution
[Description of the chosen approach]

### Implementation Details
[Technical details, affected files, key considerations]

### Alternatives Considered
[Brief mention of other approaches and why they weren't chosen]

## Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]
- [ ] Tests added/updated
- [ ] Documentation updated (if applicable)

## Additional Context
[Any other relevant information, links, screenshots, etc.]

Step 7: Review with User

Present the draft issue to the user:

• •Read through the full issue
• •Ask if anything is missing or incorrect
• •Offer to adjust scope, add details, or restructure

Iterate until the user is satisfied.

Step 8: Create the Issue

# Create the issue with conventional commit title format and appropriate labels
gh issue create \
  --title "<type>(<scope>): <description>" \
  --body "$(cat <<'EOF'
<issue body from Step 6>
EOF
)" \
  --label "<type-label>" \
  --label "<area-label>"

# Examples:
# gh issue create --title "feat(auth): Add password reset flow" \
#   --label "feature" --label "area: backend" ...

# gh issue create --title "fix(templates): Handle empty prompt gracefully" \
#   --label "bug" --label "area: backend" ...

# gh issue create --title "perf(frontend): Add session caching" \
#   --label "performance" --label "area: frontend" ...

# gh issue create --title "feat(payments): Add annual billing" \
#   --label "feature" --label "area: payments" --label "area: frontend" ...

Creating Epics with Sub-Issues:

When creating an epic with sub-issues, use GitHub's built-in sub-issue feature for automatic linking:

# 1. Create the parent issue first with epic label
gh issue create \
  --title "feat(frontend): Add dark mode support" \
  --body "$(cat <<'EOF'
## Summary
Add dark mode support to the frontend application.

## Problem / Motivation
Users have requested dark mode for comfortable evening use.

## Acceptance Criteria
- [ ] Users can toggle between light and dark mode
- [ ] Preference persists across sessions
EOF
)" \
  --label "epic" \
  --label "feature" \
  --label "area: frontend"

# Note the parent issue number (e.g., #200)

# 2. Create sub-issues using --parent flag to link automatically
gh issue create \
  --title "feat(frontend): Add theme context and toggle component" \
  --body "Sub-task for dark mode implementation." \
  --label "feature" \
  --label "area: frontend" \
  --parent 200

gh issue create \
  --title "feat(ui): Update core UI components with dark variants" \
  --body "Sub-task for dark mode implementation." \
  --label "feature" \
  --label "area: frontend" \
  --parent 200

# Sub-issues are automatically linked in the parent's task list

Benefits of using --parent:

• •Automatic bidirectional linking between parent and children
• •Progress tracking visible on parent issue
• •No need to manually update issue bodies with links

Step 9: Set Up Git Worktree for Implementation

After creating the issue, set up a dedicated git worktree for implementation:

Prerequisites Check:

1. •Ensure the current working tree is clean (no uncommitted changes)
2. •If there are uncommitted changes, ask the user how to proceed:
   • •Stash them
   • •Commit them
   • •Abort and let user handle manually

Worktree Setup:

# 1. Detect the default branch and pull latest
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git checkout $DEFAULT_BRANCH
git pull origin $DEFAULT_BRANCH

# 2. Create a new worktree with a branch for the issue
# Branch naming: <type>/<issue-number>-<short-description>
# Worktree location: ../<project>-<issue-number>
# Derive <project> from the repository name (e.g., basename of the git remote URL or directory name)
git worktree add -b <branch-name> ../<project>-<issue-number> $DEFAULT_BRANCH

# Examples:
# git worktree add -b feat/42-dark-mode ../myapp-42 main
# git worktree add -b fix/123-svg-timeout ../myapp-123 main

Branch Naming Convention:

• •Format: <type>/<issue-number>-<short-kebab-description>
• •Examples:
  • •feat/42-add-dark-mode
  • •fix/123-svg-conversion-timeout
  • •refactor/87-migrate-router
  • •docs/55-update-api-reference

After Worktree Creation:

• •Inform the user of the worktree location
• •Suggest they cd into the new worktree to begin work
• •Remind them to install dependencies in the new worktree (e.g., npm install, bun install, etc.)

Step 10: Confirm and Share

After creation:

• •Share the issue URL with the user
• •Share the worktree location and branch name
• •If multiple issues were created, list all of them with their worktree locations
• •Offer to assign the issue or add it to a project/milestone

Guidelines

Interaction Style

• •Be curious: Ask "why" and "what if" questions
• •Challenge assumptions: If something seems unclear, dig deeper
• •Offer perspective: Share what you've seen work well in similar situations
• •Stay collaborative: This is a dialogue, not a form to fill out

Quality Checks

Before finalizing, verify:

• • Title uses conventional commit format (<type>(<scope>): <description>)
• • Labels applied: At least one type label + relevant area label(s)
• • Problem is clearly articulated
• • Solution approach is justified
• • Acceptance criteria are testable
• • Scope is appropriate (not too big, not too small)
• • Implementation path is realistic
• • No critical details are missing

What NOT to Do

• •Don't create the issue without user confirmation
• •Don't assume technical approach without exploring options
• •Don't skip the alternatives analysis
• •Don't add attribution lines (Co-Authored-By, etc.)
• •Don't include time estimates (per project guidelines)
• •Don't create overly detailed implementation specs (leave room for implementer judgment)

Examples

Example Dialogue Flow

User: "We need email notifications for order updates"

Assistant: "Email notifications — great for keeping users informed. Before we scope this out, help me understand:

1. •Which order events should trigger emails (placed, shipped, delivered, cancelled)?
2. •Do we need to support email preferences (opt-in/opt-out per event type)?
3. •Is there an existing email service or should we evaluate options?

Also, let me check how notifications are currently handled in the codebase..."

[After research and discussion]

Assistant: "Based on our discussion, I see three approaches:

Option A: Transactional email service (SendGrid, Postmark)

• •Use a dedicated transactional email API
• •Template management in the service
• •Pros: Reliable delivery, analytics, easy templates
• •Cons: External dependency, cost per email

Option B: Self-hosted SMTP

• •Send via SMTP using nodemailer or similar
• •Templates stored in the codebase
• •Pros: Full control, no vendor lock-in
• •Cons: Deliverability challenges, needs monitoring

Option C: Event-driven with queue

• •Publish order events to a queue, consume asynchronously
• •Decouple email sending from order processing
• •Pros: Resilient, scalable, supports future notification channels
• •Cons: More infrastructure, higher complexity

Given the project's current scale, Option A is the simplest starting point. What's your preference?"

Example Issue Structure (Epic)

Title: feat(notifications): Add email notifications for order updates

## Summary
Send email notifications to users when their order status changes.

## Problem / Motivation
Users currently have no way to know when their order ships or gets delivered without manually checking. Email notifications improve the user experience and reduce support inquiries.

## Proposed Solution
Integrate a transactional email service to send templated emails on key order events (placed, shipped, delivered).

## Acceptance Criteria
- [ ] Users receive email when order is placed
- [ ] Users receive email when order ships with tracking info
- [ ] Users can opt out of email notifications
- [ ] Emails render correctly across major email clients

Note: Sub-issues are created separately using gh issue create --parent <ISSUE_NUMBER> and will be automatically linked by GitHub. No need to manually list them in the body.

Related Skills

Before: Use forge-setup-project to set up the project meta-structure (CLAUDE.md, docs/, etc.). Next step: Use forge-implement-issue to implement the issue you just created. Full workflow: forge-setup-project → forge-create-issue → forge-implement-issue → forge-reflect-pr → forge-address-pr-feedback → forge-update-changelog