gh-issue-report

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.

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

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

3. 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

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

   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.

5. 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

6. Fetch contributing guide and issue templates in parallel:

   # 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 bug_report.md or bug_report.yml):

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

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

8. 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:

   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.

9. 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:

   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

10. 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

11. 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

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

    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.

13. 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

14. Create the issue:

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

15. Report result:

    Filed: <issue-url>