Bug Tracker

Bug Tracker

Work the public bug tracker — the separate GitHub repo where users and testers file bug reports, feedback, and feature requests against a shipped product — through its actionable queue one issue at a time: investigate & verify, tag, mark in-progress, solve via subagent (similar to work-on-issues), comment on the tracker with resolution details, mark resolved, and close.

This handles public reports filed against a separate tracker repo with the source code located in the current working directory. The label taxonomy it drives is the one /init-bug-tracker creates.

Every comment posted to the tracker during a run starts with:

> *This was generated by AI during bug-tracker triage.*

Resolve the tracker repo

In order:

1. An explicit argument: /bug-tracker <owner/repo>. A bare issue number (/bug-tracker 42) resolves against the tracker below and jumps straight to step 2.
2. A tracker already recorded for this repo — the ### Bug tracker sub-block under ## Agent skills in CLAUDE.md or AGENTS.md.
3. Ask the maintainer which repo holds the reports, then record it there so the next run doesn't ask again.

If the taxonomy is missing or looks stale on the tracker (labels the workflow names don't exist), suggest the maintainer run /init-bug-tracker first.

Filter: actionable vs waiting

An issue is actionable when all of these hold:

1. State is OPEN.
2. It is not waiting on the reporter — no needs-info, or the reporter has commented after needs-info was applied.
3. It matches one of: unlabeled (never triaged); needs-triage; ready-for-agent or ready-for-human; or a bug / enhancement / feedback label with no blocking label.

Ignored: needs-info without reporter activity, in-progress with an active assignee/run, wontfix, resolved (already closed/resolved).

Workflow

1. Fetch and present the queue

REPO="<owner/repo>"
gh issue list -R "$REPO" --state open --json number,title,labels,author,createdAt,updatedAt,comments

Sort into queues, oldest first, and present one table (# | Title | Category | State | Author | Age):

• Queue A — needs attention: unlabeled or needs-triage.
• Queue B — reporter replied: needs-info with reporter comments newer than the last triage note.
• Queue C — ready for execution: ready-for-agent / ready-for-human.

Begin with the oldest issue in Queue A or B; the maintainer may override the pick by naming an issue number.

2. Investigate, verify, and tag

1. Read the full conversation and timeline:

   gh issue view <number> -R "$REPO" --comments
   

   Read the initial description, environment details (OS, version), reproduction steps, and every subsequent comment and reply from the reporter, testers, and maintainers. Parse prior triage notes to avoid re-asking what was already clarified.

2. Extract and inspect attachments (screenshots, sample files, logs):

   • Parse all URLs, image markdown (![...](url)), GitHub asset uploads (https://github.com/user-attachments/assets/... or https://github.com/.../assets/...), and attached logs from the issue body and comments.
   • Screenshots & UI images: Download and inspect visually via multimodal Read (or curl to /tmp/ and inspect) to examine error dialogs, visual glitches, unexpected layouts, or clipping.
   • Sample files & documents: Download sample files to /tmp/ (e.g., curl -sL "<url>" -o /tmp/issue-<number>-sample.pdf) and inspect their structure (headers, streams, metadata) using local tools or scripts.
   • Console logs & crash reports: Inspect full stack traces, IPC call names, unhandled rejections, and version info.

3. Cross-reference the source in this working directory:

   • Locate the relevant subsystem, recent commits, and existing tests.
   • Trace the exact code path indicated by logs, attachments, or reproduction steps.
   • Verify whether the problem reproduces locally and pinpoint the root cause.

4. Tag the issue with suitable labels: Determine the appropriate taxonomy tags:

   • Category: bug, enhancement, feedback, documentation, or question
   • Priority: priority:critical, priority:high, priority:medium, or priority:low
   • Area: area:<slug> (matching the product components initialized by /init-bug-tracker)
   • Verification: tester-verified (if reproduced/verified in code) or needs-reproduction (if reproduction steps are missing or cannot reproduce)

   Apply the classification labels to the issue on the tracker:

   gh issue edit <number> -R "$REPO" \
     --add-label "bug,area:<component>,priority:<level>,tester-verified"
   

5. Handle non-solvable or blocked outcomes:

   • Out of scope / wontfix:

     gh issue close <number> -R "$REPO" --reason "not planned" \
       --comment "> *This was generated by AI during bug-tracker triage.*\n\nClosed as out of scope / working as intended: <explanation>."
     gh issue edit <number> -R "$REPO" --add-label "wontfix" --remove-label "needs-triage,in-progress"
     

     Advance to next issue.
   • Needs information from reporter (needs-info): Post a comment naming the exact missing reproduction step, sample file, or log (never "please provide more info"):

     gh issue comment <number> -R "$REPO" \
       --body "> *This was generated by AI during bug-tracker triage.*\n\n### Needs Information\n<specific questions for reporter>"
     gh issue edit <number> -R "$REPO" --add-label "needs-info" --remove-label "needs-triage,in-progress"
     

     Advance to next issue.
   • Requires human action (ready-for-human): If the issue requires manual UX design, product decision, or physical hardware testing:

     gh issue comment <number> -R "$REPO" \
       --body "> *This was generated by AI during bug-tracker triage.*\n\n### Triage Note\nRequires manual/human action: <reason>"
     gh issue edit <number> -R "$REPO" --add-label "ready-for-human" --remove-label "needs-triage,in-progress"
     

     Advance to next issue.

3. Mark as in-progress & prepare workspace

When proceeding to solve the issue:

1. Mark in-progress on the tracker:

   gh issue edit <number> -R "$REPO" \
     --add-label "in-progress" \
     --remove-label "needs-triage,ready-for-agent"
   

2. Create isolated git worktree:

   git worktree add .claude/worktrees/issue-<number> -b work-on-issue-<number>
   

3. Copy .env files: Copy .env and .env.* files into the worktree directory if they exist in the root.

4. Solve in subagent

Sub-agent only. The orchestrator delegates implementation to a dispatched subagent inside .claude/worktrees/issue-<number>. The orchestrator does not edit code or run tests directly.

Dispatch the subagent (using haiku or configured model) with a complete, self-contained prompt:

Implement bug fix / feature for issue #<number>: <title>.

Issue body (verbatim):
<full issue description — reproduction steps, environment, symptoms>

Issue comments & attachments summary:
<all relevant comments and investigation findings, root cause, reproduction details>

Working Directory / Worktree:
.claude/worktrees/issue-<number> on branch work-on-issue-<number>

Implementation instructions:
1. Fix the verified root cause in the codebase.
2. Write tests covering the reproduction case to prevent regression (TDD).
3. Research: If you encounter 2+ consecutive failures or unfamiliar APIs, search via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch before retrying.
4. Parallel subtasks: Decompose and dispatch child sub-agents if subtasks are independent and touch non-overlapping files.
5. Post-implementation verification:
   - Run tests to verify the fix passes and no existing tests break.
   - Run `/find-mismatch` skill on modified files only.
   - If TypeScript/JavaScript codebase, run `npx fallow audit` (install fallow if not present) and resolve any findings.
6. Commit changes:
   Format: `fix: resolve #<number> — <short description>` (or `feat: resolve #<number> — <short description>`)

Return: Summary of root cause, changes made, tests run, and commit hash.

5. Submit, comment, mark resolved, and close

Once the subagent completes the fix and commits changes:

1. Propagate .env files back: Copy any modified env files from the worktree back to the main directory:

   WT=.claude/worktrees/issue-<number>
   for wtf in "$WT"/.env "$WT"/.env.*; do
     [ -f "$wtf" ] || continue
     base=$(basename "$wtf")
     if [ ! -f "$base" ] || ! cmp -s "$base" "$wtf"; then
       cp "$wtf" "$base" && echo "Propagated $base back"
     fi
   done
   

2. Merge changes & clean up worktree: Merge the branch into the active branch (or submit PR if repository workflow requires it):

   git merge --no-ff work-on-issue-<number> -m "fix: resolve #<number> — <short description>"
   git worktree remove .claude/worktrees/issue-<number>
   git branch -d work-on-issue-<number>
   

3. Add resolution comment to the public tracker repo: Post a comprehensive resolution summary with the required AI disclaimer:

   gh issue comment <number> -R "$REPO" --body "> *This was generated by AI during bug-tracker triage.*
   
   ### Resolution summary
   - **Root cause**: <explanation of root cause>
   - **Fix**: <summary of changes applied in source repo>
   - **Verification**: <tests added/run and verification results>"
   

4. Mark as resolved and close the issue on the tracker:

   gh issue edit <number> -R "$REPO" \
     --add-label "resolved" \
     --remove-label "in-progress,ready-for-agent,needs-triage"
   
   gh issue close <number> -R "$REPO" --reason "completed"
   

6. Advance

Announce the resolution of #<number>, display the updated queue status table, and load the next actionable issue. Continue until the actionable queue is empty or the maintainer stops the session.