# Bug Tracker

> Use to work the actionable queue of a public GitHub bug tracker — investigating, tagging, solving issues in subagents, commenting on the tracker, and closing.

- Skill: `utarn/bug-tracker` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add utarn/bug-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/utarn/bug-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: utarn (https://skillmd.com/u/utarn)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/utarn/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:

```markdown
> *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

```bash
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:**
   ```bash
   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:
   ```bash
   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**:
     ```bash
     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"):
     ```bash
     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:
     ```bash
     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**:
   ```bash
   gh issue edit <number> -R "$REPO" \
     --add-label "in-progress" \
     --remove-label "needs-triage,ready-for-agent"
   ```

2. **Create isolated git worktree**:
   ```bash
   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:

```markdown
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:
   ```bash
   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):
   ```bash
   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:
   ```bash
   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**:
   ```bash
   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.