Create GitHub Issue with Research Integration

Automate GitHub issue creation with research-backed, well-structured content.

Modes

Mode	Time	Description
Default (thorough)	8-12 min	Full analysis, blocking duplicate check
--quick	3-5 min	Async scan, smart sections, no prompts

Implementation

CRITICAL: Follow these steps in order. Each checkpoint validates before proceeding.

ARGUMENTS: {{ARGUMENTS}}

---

STEP 0: Parse Arguments and Mode

Parse the ARGUMENTS to detect mode flags:

--quick       Fast mode (async scan, smart sections, no prompts)
--thorough    (Deprecated - silently accepted, now default behavior)

Default mode: Thorough mode with full analysis, blocking duplicate check, all sections.

Extract the feature request (everything except flags).

---

STEP 1: Research + Async Issue Scan (Parallel)

Launch TWO agents in parallel using the Task tool:

Agent 1: researcher (subagent_type="researcher")

• Search codebase for similar patterns
• Research best practices and security considerations
• Identify recommended approaches

Agent 2: issue-scanner (subagent_type="Explore", run_in_background=true)

• Quick scan of existing issues for duplicates/related
• Use: gh issue list --state all --limit 100 --json number,title,body,state
• Look for semantic similarity to the feature request
• Confidence threshold: >80% for duplicate, >50% for related

CRITICAL: Use a single message with TWO Task tool calls to run in parallel.

---

CHECKPOINT 1: Validate Research Completion

Verify the researcher agent completed successfully:

• Research findings documented
• Patterns identified
• Security considerations noted (if relevant)

If research failed, stop and report error. Do NOT proceed to STEP 2.

Note: Issue scan runs in background - results retrieved in STEP 3.

---

STEP 2: Generate Issue with Deep Thinking Methodology

Use the Task tool to invoke the issue-creator agent (subagent_type="issue-creator") with:

• Original feature request (from ARGUMENTS)
• Research findings (from STEP 1)
• Mode flag (default or thorough)

Deep Thinking Template (issue-creator should follow - GitHub Issue #118):

ALWAYS include:

1. Summary: 1-2 sentences describing the feature/fix

2. What Does NOT Work (negative requirements):

   • Document patterns/approaches that fail
   • Prevents future developers from re-attempting failed approaches
   • Example: "Pattern X fails because of Y"

3. Scenarios (update vs fresh install):

   • Fresh Install: What happens on new system
   • Update/Upgrade: What happens on existing system
     • Valid existing data: preserve/merge
     • Invalid existing data: fix/replace with backup
     • User customizations: never overwrite

4. Implementation Approach: Brief technical plan

5. Test Scenarios (multiple paths, not just happy path):

   • Fresh install (no existing data)
   • Update with valid existing data
   • Update with invalid/broken data
   • Update with user customizations
   • Rollback after failure

6. Acceptance Criteria (categorized):

   • Fresh Install: [ ] Creates correct files, [ ] No prompts needed
   • Updates: [ ] Preserves valid config, [ ] Fixes broken config
   • Validation: [ ] Reports issues clearly, [ ] Provides fix commands
   • Security: [ ] Blocks dangerous ops, [ ] Protects sensitive files

Include IF relevant (detect from research):

• Security Considerations: Only if security-related
• Breaking Changes: Only if API/behavior changes
• Dependencies: Only if new packages/services needed
• Environment Requirements: Tool versions, language versions where verified
• Source of Truth: Where the solution was verified, date, attempts

NEVER include (remove these filler sections):

• Limitations (usually empty)
• Complexity Estimate (usually inaccurate)
• Estimated LOC (usually wrong)
• Timeline (scheduling not documentation)

--quick mode: Include only essential sections (Summary, Implementation, Test Scenarios, Acceptance Criteria).

Default mode: Include ALL sections with full detail.

---

CHECKPOINT 2: Validate Issue Content (Deep Thinking)

Verify the issue-creator agent completed successfully:

• Issue body generated
• Required sections present:
  • Summary (1-2 sentences)
  • What Does NOT Work (negative requirements)
  • Scenarios (fresh install + update behaviors)
  • Implementation Approach
  • Test Scenarios (multiple paths)
  • Acceptance Criteria (categorized)
• Content is well-structured markdown
• Body length < 65,000 characters (GitHub limit)
• No empty sections ("Breaking Changes: None" - remove these)
• No filler (no "TBD", "N/A" unless truly not applicable)

If issue creation failed, stop and report error. Do NOT proceed to STEP 3.

---

STEP 3: Retrieve Scan Results + Create Issue

3A: Retrieve async scan results

Use TaskOutput tool to retrieve the issue-scanner results (non-blocking, timeout 5s).

If scan found results:

• Duplicates (>80% similarity): Store for post-creation info
• Related (>50% similarity): Store for post-creation info

Default mode: If duplicates found, prompt user before creating:

Potential duplicate detected:
  #45: "Implement JWT authentication" (92% similar)

Options:
1. Create anyway (may be intentional)
2. Skip and link to existing issue
3. Show me the existing issue first

Reply with option number.

--quick mode: No prompts. Create issue, show info after.

3B: Create GitHub issue via gh CLI

Extract the issue title and body from the issue-creator agent output.

Use the Bash tool to execute:

gh issue create --title "TITLE_HERE" --body "BODY_HERE"

Security: Title and body are validated by issue-creator agent. If gh CLI fails, provide manual fallback.

---

CHECKPOINT 3: Validate Issue Creation

Verify the gh CLI command succeeded:

• Issue created successfully
• Issue number returned (e.g., #123)
• Issue URL returned

---

STEP 4: Post-Creation Info + Research Cache

4A: Display related issues (informational)

If the async scan found related/duplicate issues, display them AFTER creation:

Issue #123 created successfully!
  https://github.com/owner/repo/issues/123

Related issues found (consider linking):
  #12: "Add user authentication" (65% similar)
  #45: "OAuth2 integration" (58% similar)

Tip: Link related issues with:
  gh issue edit 123 --body "Related: #12, #45"

4B: Cache research for /auto-implement reuse

Save research findings to .claude/cache/research_<issue_number>.json:

{
  "issue_number": 123,
  "feature": "JWT authentication",
  "research": {
    "patterns": [...],
    "best_practices": [...],
    "security_considerations": [...]
  },
  "created_at": "2025-12-13T10:30:00Z",
  "expires_at": "2025-12-14T10:30:00Z"
}

This cache is used by /auto-implement to skip duplicate research.

---

STEP 5 (MANDATORY): Validation and Review

STOP: Before proceeding, the user MUST validate and review the created issue.

Display the following message:

Issue #123 created successfully!
  https://github.com/owner/repo/issues/123

**MANDATORY NEXT STEP**: Review and validate the issue before implementation

Please review the issue content at the URL above and confirm:
- [ ] Summary is accurate
- [ ] Implementation approach is correct
- [ ] Test scenarios cover all paths
- [ ] Acceptance criteria are complete

Once you've reviewed the issue, you can proceed with implementation:
  /auto-implement "#123"

This workflow ensures:
- ✅ Issue is validated before work begins
- ✅ Research is cached and reused (saves 2-5 min)
- ✅ Full traceability from issue to implementation

**Estimated implementation time**: 15-25 minutes

Wait for confirmation before proceeding. User must confirm they have reviewed the issue.

Why This Is Mandatory:

• Prevents implementing issues with incorrect requirements
• Ensures user validates research findings before committing to implementation
• Provides opportunity to revise issue before starting work
• Maintains audit trail from issue to implementation

DO NOT automatically proceed to /auto-implement without explicit user confirmation.

User must approve before continuing. Require confirmation that the issue has been validated.

---

What This Does

Step	Time	Description
Research + Scan	2-3 min	Parallel: patterns + issue scan
Generate Issue	5-8 min	All sections with full detail
Duplicate Check	1-2 min	Blocking user prompt (if duplicates found)
Create + Info	15-30 sec	gh CLI + related issues
Total	8-12 min	Default mode (thorough)
Total (--quick)	3-5 min	Fast mode (async scan only)

---

Usage

# Default mode (thorough, all sections, blocking duplicate check)
/create-issue Add JWT authentication for API endpoints

# Quick mode (fast, smart sections, no prompts)
/create-issue Add JWT authentication --quick

# Bug report (thorough by default)
/create-issue Fix memory leak in background job processor

---

Prerequisites

Required:

• gh CLI installed: https://cli.github.com/
• gh CLI authenticated: gh auth login
• Git repository with GitHub remote

---

Error Handling

gh CLI Not Installed

Error: gh CLI is not installed

Install gh CLI:
  macOS: brew install gh
  Linux: See https://cli.github.com/
  Windows: Download from https://cli.github.com/

After installing, authenticate:
  gh auth login

gh CLI Not Authenticated

Error: gh CLI is not authenticated

Run: gh auth login

Duplicate Detected (default mode)

Potential duplicate detected:
  #45: "Implement JWT authentication" (92% similar)

Options:
1. Create anyway
2. Skip and link to existing
3. Show existing issue

Reply with option number.

Note: Use --quick flag to skip this prompt and create immediately.

---

Integration with /auto-implement

When /auto-implement "#123" runs on an issue created by /create-issue:

1. Check research cache: .claude/cache/research_123.json
2. If found and not expired (24h TTL):
   • Skip researcher agent (saves 2-5 min)
   • Use cached patterns, best practices, security considerations
   • Start directly with planner agent
3. If not found or expired:
   • Run researcher as normal

This integration saves 2-5 minutes when issues are implemented soon after creation.

---

Technical Details

Agents Used:

• researcher: Research patterns and best practices (Haiku model, 2-3 min)
• issue-creator: Generate structured issue body (Sonnet model, 1-2 min)
• Explore: Quick issue scan for duplicates/related (background, <30 sec)

Tools Used:

• gh CLI: Issue listing and creation
• TaskOutput: Retrieve background scan results

Security:

• CWE-78: Command injection prevention (no shell metacharacters in title)
• CWE-20: Input validation (length limits, format validation)

Performance:

• Default mode: 8-12 minutes (thorough, with prompts)
• Quick mode: 3-5 minutes (fast, no prompts)

---

Part of: Core workflow commands Related: /auto-implement, /align Enhanced in: v3.41.0 (GitHub Issues #118, #122)