Creating Issues

Phase 1: Search Duplicates (MANDATORY)

CRITICAL: Always search exhaustively BEFORE creating a new issue. Many issues have already been reported. Adding a +1 to an existing issue is MORE valuable than creating a duplicate.

1. Determine type:

• Feature request: New functionality, enhancement
• Bug report: Broken, not working, error

2. Search with MULTIPLE keyword variations:

# Search at least 3-5 different keyword combinations
gh search issues --repo anthropics/claude-code "input buffer" --limit 15
gh search issues --repo anthropics/claude-code "text disappear" --limit 15
gh search issues --repo anthropics/claude-code "prompt lost" --limit 15
gh search issues --repo anthropics/claude-code "race condition" --limit 15

Keyword strategy:

• Use synonyms (input/prompt/text, lost/disappear/cleared)
• Try both technical terms ("race condition", "buffer") and user descriptions ("disappears", "gone")
• Search for the symptom AND the cause

3. Check duplicates thoroughly:

• Show similar issues (titles, URLs)
• View potential duplicates: gh issue view --repo anthropics/claude-code [number] --comments
• Follow duplicate chains (issues often reference canonical issues)
• Check if user already engaged (commented, reacted)
• Ask: "Do any match what you're reporting?"

4. If duplicate found:

• Not engaged: Add detailed +1 comment with your specific scenario

  gh issue comment --repo anthropics/claude-code [number] --body "+1 Still experiencing this in v2.x. [Add your specific details]"
  

• Already engaged: Note participation, end workflow

5. Only proceed to Phase 2 if NO duplicates found after thorough search.

Phase 2: Learn Format

CRITICAL: Don't impose fixed template. Learn from repo.

1. Fetch similar issues:

# Feature requests
gh search issues --repo anthropics/claude-code "is:issue label:enhancement" --limit 5

# Bug reports
gh search issues --repo anthropics/claude-code "is:issue label:bug" --limit 5

2. Analyze structure:

gh issue view --repo anthropics/claude-code [number]

3. Identify patterns:

• Sections used (Problem, Solution, Steps to Reproduce)
• Detail level (brief vs comprehensive)
• Checklists, code blocks, examples
• Tone (formal vs casual)
• Component tags

4. Extract template:

• Consistent sections
• Optional vs required
• Markdown patterns

Phase 3: Draft Issue

1. Apply learned structure:

• Match repository patterns
• Match detail level
• Use similar formatting
• Adopt appropriate tone

2. Feature Request Structure (adapt):

## Problem / Use Case
[What trying to do or what's missing]

## Proposed Solution
[What to add or change]

## Example Usage
[Concrete example]

## Additional Context
[Optional: screenshots, related issues]

3. Bug Report Structure (adapt):

## Description
[What's happening vs should happen]

## Steps to Reproduce
1. [First]
2. [Second]
3. [Third]

## Expected / Actual Behavior
Expected: [what should happen]
Actual: [what happens]

## Environment
- Claude Code version: [version]
- OS: [OS]

## Additional Context
[Optional: errors, screenshots, logs]

4. Gather information:

• Ask clarifying questions based on learned format
• Request details from similar issues
• Keep conversational

Phase 4: Preview & Refine

1. Show draft:

════════════════════════════════════════
📋 DRAFT ISSUE: [Type]
════════════════════════════════════════
🏷️  TITLE: [Clear, searchable title]

📝 BODY:
[Full content]

📊 METADATA:
- Type: [Feature/Bug]
- Labels: [Suggested]
- Similar: [Related issue numbers]
════════════════════════════════════════

2. Get feedback:

• "Does this capture what you want?"
• "Submit or adjust?"

3. Iterate if needed

Phase 5: Submit

1. Only with explicit approval ("yes", "submit", "go ahead")

2. Create:

gh issue create \
  --repo anthropics/claude-code \
  --title "[title]" \
  --body "$(cat <<'EOF'
[content]
EOF
)"

3. Confirm:

✅ Issue #[number]: [title]
🔗 URL: [URL]

View: gh issue view --repo anthropics/claude-code [number]

Advanced

Specific issue format:

gh issue view --repo anthropics/claude-code [reference-number]

Other repos:

gh search issues --repo [owner/repo] "{terms}"

Label suggestions:

gh label list --repo anthropics/claude-code
# Suggest: bug, enhancement, documentation, plugin, mcp, hooks

Best Practices

Feature Requests:

• Start with "why"
• Concrete examples
• Open to alternatives
• Link related issues
• Consider scope

Bug Reports:

• Exact steps
• Include context (version, OS)
• Actual vs expected
• Evidence (errors, screenshots)
• Minimal reproduction

General:

• Clear, searchable titles
• One issue per report
• Search first
• Be respectful
• Follow up

Quick Reference

# Search (use MULTIPLE variations)
gh search issues --repo anthropics/claude-code "{terms}" --limit 15
gh search issues --repo anthropics/claude-code "{synonym1}" --limit 15
gh search issues --repo anthropics/claude-code "{synonym2}" --limit 15

# View with comments (to check for user engagement)
gh issue view --repo anthropics/claude-code [number] --comments

# +1 existing issue (PREFERRED over creating duplicate)
gh issue comment --repo anthropics/claude-code [number] --body "+1 Still experiencing this. [specific details]"

# Create (only after exhaustive search)
gh issue create --repo anthropics/claude-code --title "Title" --body "Body"

# Labels
gh label list --repo anthropics/claude-code