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

• Verify external dependencies: If the issue involves external services, APIs, or third-party tools, run a quick smoke test to confirm they’re accessible and working. Flag any issues to the user before proceeding to solution design — building on broken dependencies wastes entire sessions.

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]

### Implementation Constraints
[Include when the issue involves choices between libraries, APIs, configuration approaches, or non-obvious patterns]
- Preferred libraries or tools: <what to use and what to avoid>
- Configuration location: <where settings should live>
- Patterns to follow: <reference existing patterns in the codebase>
- External dependencies: <services or APIs required, and how to verify they work>

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