/bug-audit

name: bug-audit
description: Weekly multi-agent audit for serious bugs (data integrity, silent caps, staleness, timestamp math, trust boundaries). Fans out Sonnet scanners + Opus deep auditors, adversarially verifies every finding, files GitHub issues for confirmed critical/high bugs. Trigger: /bug-audit

bug-audit — weekly serious-bug sweep

Multi-agent audit of the TokenTelemetry backend/frontend for the bug class that motivated it (PR #131: a silent 100-session cap plus stub rows crushing real persisted data). Optimized for bugs that **corrupt data, lose data, or silently report wrong numbers** — not style or hypotheticals.

Scope selection (do this first)

1. Find the last audit marker: the most recent GitHub issue labeled `bug-audit` (`gh issue list --label bug-audit --state all --limit 1`), whose body records the commit it audited up to. 2. Primary scope = `git diff <last-audited-commit>..HEAD` plus any file those diffs touch. If no marker exists (first run), scope = `backend/*.py` and `frontend/src/lib` + `frontend/src/app`. 3. Always include the standing hot-spots regardless of diff: `backend/main.py` scan loops, `backend/history_store.py`, `backend/scan_cache.py` (if present), anything matching `backend/*cache*`/`backend/*store*`.

Fan-out (Agent tool; run each wave's spawns in parallel)

**Wave 1 — breadth, `audit-scanner` (Sonnet), one per dimension:**

• silent caps & truncation (slices, LIMIT, early breaks, `[:N]`)
• persisted-state integrity (upserts that overwrite, absent-vs-zero

confusion, stub/partial rows)

• cache & staleness (mtime keys, missing version fields, invalidation gaps)
• timestamp/timezone math (naive datetimes, mtime-as-date, day bucketing)
• trust boundaries (on-disk ids/paths/cwd used in paths, SQL, shell)
• token/cost arithmetic (double counting, high-water-mark vs sum, unit slips)

Give each scanner the scope file list and its dimension. Prompt them to return the FINDING-block format their agent definition specifies.

**Wave 2 — depth, `audit-deep` (Opus), in the same parallel batch as wave 1:** one per risky subsystem actually present in scope, typically 2-4 of:

• scan → cache → history-upsert pipeline (the PR #131 path)
• one agent-store parser that changed recently (Claude, Codex, Copilot…)
• any new persisted format introduced since the last audit
• the analytics aggregation path (`/analytics`, ecosystem rollups)

**Wave 3 — verification, `audit-verifier` (Opus), one per candidate:** Dedupe wave 1+2 candidates by (file, defect) first. Send each survivor to a verifier with the full finding block. Only `VERDICT: CONFIRMED` findings survive; keep the verifier's own severity, not the scanner's.

Output

1. Write the report to `docs/audits/<YYYY-MM-DD>-bug-audit.md`: audited range (`<from>..<to>` commits), confirmed findings (severity, file:line, scenario, verifier's reason), refuted-candidate count, dimensions that came back clean. 2. File one GitHub issue per confirmed **critical or high** finding: `gh issue create --label bug,bug-audit` — title is the one-sentence defect, body is the finding block + verifier reason + audited commit. Medium findings go only in the report. 3. Always file/update the audit-marker issue: a single issue titled `bug-audit marker` labeled `bug-audit` whose body's last line is `audited-through: <HEAD sha>` (edit it if it exists, create otherwise). 4. Commit the report on a branch `audit/<YYYY-MM-DD>` and open a draft PR (report only — never commit fixes from this skill; fixes are separate, human-initiated work).

Weekly cadence

Run manually with `/bug-audit`, or schedule headless:

# launchd/cron, weekly:
cd /path/to/tokentelemetry && claude -p "/bug-audit" --permission-mode acceptEdits

Budget note: one run spawns roughly 6 Sonnet scanners + 2-4 Opus deep auditors + one Opus verifier per candidate. If candidates exceed ~15, verify only critical/high candidates and list the rest as unverified in the report.