---
name: bug-tracker
description: "File, list, update, and close bugs/features/tasks/client-projects in the Gitea issue tracker across GuruRMM, GuruConnect, and ClaudeTools repos. Live dashboard at tracker.azcomputerguru.com. Triggers: file a bug, track a bug, open an issue, bug tracker, what bugs are open, list bugs, close issue, update issue, mark fixed, what is being worked on."
---

# Bug & Project Tracker — Gitea Issues

Live client for the ACG bug/feature/skill/project/client-project tracker. All data lives in
Gitea Issues — no separate database. The web dashboard and this skill are two interfaces
to the same data.

- **Dashboard:** https://tracker.azcomputerguru.com/dashboard.html
- **Direct:** http://172.16.3.20:8089/dashboard.html

## Running

```bash
BT=".claude/skills/bug-tracker/scripts/tracker.py"

# --- reads ---
py "$BT" status                                          # issue counts across all repos
py "$BT" list                                            # all open issues, all repos
py "$BT" list --repo gururmm --type bug                  # gururmm bugs only
py "$BT" list --type client-project --client cascades     # Cascades client projects
py "$BT" list --state closed --json                       # closed issues as JSON
py "$BT" show gururmm 39                                  # detail + comments for gururmm #39

# --- writes ---
py "$BT" create --repo claudetools --title "vault: X fails" \
    --body "Error detail here" --type bug --priority P2-high \
    --component component:harness --discovered 2026-07-18

py "$BT" create --repo claudetools --title "Cascades: new project" \
    --body "Description" --type client-project --priority P3-normal \
    --client cascades --assign howard --discovered 2026-07-18

py "$BT" comment gururmm 39 --body "Tried X, still reproduces"
py "$BT" priority gururmm 39 --set P1-critical
py "$BT" assign claudetools 5 --to mike
py "$BT" label gururmm 39 --add in-progress
py "$BT" label gururmm 39 --remove blocked
py "$BT" close claudetools 7 --comment "Fixed in commit abc123"
py "$BT" reopen claudetools 7
```

## Credentials

Token loaded at runtime from the SOPS vault (never hardcoded):
**`services/gitea`** -> `credentials.api.api-token`.
Falls back to `GITEA_TOKEN` env var if vault is unavailable.

## Tracked repos

| Repo | What it tracks |
|------|---------------|
| `gururmm` | RMM agent/server/dashboard bugs, features, security |
| `guru-rmm` | RMM code review tracking |
| `guru-connect` | GuruConnect bugs, security audit findings |
| `claudetools` | Harness/skill bugs, skill work, projects, **all client projects** |

## Label scheme

| Category | Labels |
|----------|--------|
| Type | `bug` `feature` `skill` `project` `security` `client-project` |
| Priority | `P1-critical` `P2-high` `P3-normal` `P4-low` |
| Status | `in-progress` `blocked` `dropped` `fixed` `verified` `wontfix` |
| Component | `component:rmm-agent` `component:rmm-server` `component:rmm-dashboard` `component:guruconnect` `component:harness` |
| Client | `client:<slug>` (e.g. `client:cascades`, `client:dataforth`) |
| Assignee | `assigned:howard` `assigned:mike` |

Always include: one type label + one priority label. Add component/client/assignee as applicable.

## Auto-filing (IMPORTANT)

When a bug surfaces during a Claude session — a command fails unexpectedly, a skill
hits an error that needs follow-up, or the user reports something broken — **file it
as an issue** using this script (with user confirmation for title/priority). This is
the whole point: bugs should not require someone to remember them.

The issue body should include:
- What happened (error message, unexpected behavior)
- Context (what was being attempted, which machine, which session)
- Any workaround applied
- A `**Discovered:** YYYY-MM-DD` line so the dashboard shows accurate age

Do NOT file:
- Client machine problems (PacketDial 404s, Intune device metrics, client network issues)
- Vendor API limitations we cannot fix
- One-off env/friction issues that are already resolved

## Error logging

On any failure (API error, label not found, vault unavailable), log it:
```bash
bash .claude/scripts/log-skill-error.sh "bug-tracker" "brief error description" --context "cmd=create repo=claudetools"
```

## Relationship to the dashboard

The dashboard at tracker.azcomputerguru.com is a single-page HTML app that makes the
same Gitea API calls this script does. There is no sync, no cache, no separate database.
An issue created by this script appears on the dashboard immediately. An issue edited
on the dashboard is visible to this script immediately. They are the same data.

Dashboard infrastructure: Docker container `acg-tracker` on Jupiter (172.16.3.20:8089),
proxied through NPM with Let's Encrypt SSL. Files at `/mnt/user/appdata/acg-tracker/`.
To update the dashboard: upload new `dashboard.html` via SFTP, `docker restart acg-tracker`.

$ARGUMENTS
