11 KiB

Raw Blame History

name

description

argument_hint

allowed-tools

create-issue

Create GitHub issue with automated research (--quick for fast mode)

Issue title [--quick] (e.g., 'Add JWT authentication' or 'Add JWT authentication --quick')

Task

Read

Bash

Grep

Glob

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:

Summary: 1-2 sentences describing the feature/fix
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"
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
Implementation Approach: Brief technical plan
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
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:

Check research cache: .claude/cache/research_123.json
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
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)

11 KiB Raw Blame History