Issue Report

Investigate a bug, confirm it hasn't been reported, optionally verify in source code, and file a structured issue — all in one workflow.

Arguments

• /gh-issue-report — interactive: asks for repo and bug description
• /gh-issue-report <owner/repo> <description> — uses arguments directly

Phase 1: Intake

1. Resolve target repo:

- If argument includes owner/repo, use it. - If the current directory is a git repo, offer it as default. - Otherwise, ask.

1. Bug description: If provided as argument, use it. Otherwise ask:

> What bug are you seeing? Include steps to reproduce if you have them.

1. Determine repo locality:

- Check if the repo is cloned locally (look for matching remote in git remote -v or check common paths). - Local: use file system tools (Read, Grep, Glob) for code investigation. - Remote-only: use gh api to fetch repo contents for code investigation.

Phase 2: Search Existing Issues

1. Search for duplicates using multiple query strategies in parallel:

``bash gh issue list -R <repo> --state all --search "<keywords from description>" --limit 20 ``

Run 2-3 searches with different keyword combinations extracted from the bug description (e.g., key nouns, component names, error messages). Cast a wide net.

1. Evaluate matches:

- If a clear duplicate exists: show it to the user and ask whether to proceed or comment on the existing issue. - If partial matches exist: show them and note the differences. - If no matches: continue.

Phase 3: Check Repo Conventions

1. Fetch contributing guide and issue templates in parallel:

```bash # Contributing guide gh api 'repos/<repo>/contents/CONTRIBUTING.md' --jq '.content' | base64 -d

# Issue templates gh api 'repos/<repo>/contents/.github/ISSUE_TEMPLATE' --jq '.[].name' ```

If issue templates exist, fetch the relevant one (usually bugreport.md or bugreport.yml):

``bash gh api 'repos/<repo>/contents/.github/ISSUE_TEMPLATE/<template>' --jq '.content' | base64 -d ``

1. Extract conventions: note title prefix (e.g., [bug]), required labels, required sections, and any special instructions from the contributing guide.

Phase 4: Code Investigation

Adapt investigation depth based on what's achievable. Start lightweight; go deeper only when the lightweight pass yields promising leads.

1. Lightweight pass — identify relevant files:

For local repos: `` Use Grep/Glob to find files matching component names, error messages, or keywords from the bug description. ``

For remote repos: ``bash gh api 'repos/<repo>/git/trees/main?recursive=1' --jq '.tree[].path' | grep -iE '<keywords>' ``

If this yields no useful results (no matching files, or too many to be actionable), skip to Phase 5 and draft the issue without code-level root cause. Note in the issue body that root cause was not confirmed in code.

1. Deep investigation — if the lightweight pass found relevant files (< 10 candidates), read them to understand the bug:

For local repos: use Read tool directly.

For remote repos: ``bash gh api 'repos/<repo>/contents/<path>' --jq '.content' | base64 -d ``

Use subagents for parallel investigation when reading multiple files. Focus on: - Where the relevant state is stored (React state, store, DB, etc.) - What triggers the bug (lifecycle, navigation, race condition, etc.) - Why the current implementation fails

1. Assess findings:

- Root cause confirmed: include it in the issue with file paths and line references. - Suspected but unconfirmed: include as hypothesis, clearly labeled. - Nothing actionable found: omit code analysis from the issue, describe only the observed behavior.

Phase 5: Draft Issue

1. Compose the issue following the repo's template and conventions:

Always include: - Title: follow repo convention (e.g., [bug] ...), keep under 80 chars - Description: clear, concise explanation of the bug - Steps to reproduce: numbered list - Expected vs actual behaviour

Include when available: - Root cause: with file paths and line references from Phase 4 - Suggested fix: if root cause is clear enough to propose a direction - Environment: platform, version, relevant config

1. Infer labels: fetch repo labels and match against the issue content:

``bash gh label list -R <repo> --json name,description --jq '.[] | "\(.name)\t\(.description)"' ``

Only use labels that exist on the repo. If the template specifies a label (e.g., bug), use it.

1. Present draft to user:

> Here's the issue I'll file. Want me to adjust anything?

Show the full title, labels, and body. Wait for approval.

Phase 6: File Issue

1. Create the issue:

``bash gh issue create -R <repo> \ --title "<title>" \ --label "<labels>" \ --body "$(cat <<'EOF' <body> EOF )" ``

1. Report result:

`` Filed: <issue-url> ``