Bug Scrub

Perform a comprehensive project health check by collecting signals from multiple sources, aggregating findings into a unified schema, and producing a prioritized report.

This is a read-only diagnostic skill — it does not modify any code. Use /fix-scrub to remediate findings.

Arguments

$ARGUMENTS - Optional flags:

• --source <list> (comma-separated sources; default: all available)
• --severity <level> (minimum severity: critical, high, medium, low, info; default: low)
• --project-dir <path> (directory with pyproject.toml; default: auto-detect)
• --out-dir <path> (default: docs/bug-scrub)
• --format <md|json|both> (default: both)
• --candidate-work-output <path> (default: adjacent bug-scrub-candidate-work.json)

Valid sources: pytest, ruff, mypy, openspec, architecture, security, deferred, markers, github-issues

Script Location

Scripts live in <agent-skills-dir>/bug-scrub/scripts/. Each agent runtime substitutes <agent-skills-dir> with its config directory:

• Claude: .claude/skills
• Codex: .codex/skills
• Gemini: .gemini/skills

Installed skill copies are expected to include these scripts. If they are missing,
reinstall the skill from its canonical distribution rather than invoking a repo-local path.

Prerequisites

• Python 3.11+
• Project tools installed (pytest, ruff, mypy — collectors skip unavailable tools)
• OpenSpec CLI for openspec source
• Authenticated GitHub CLI (gh) for github-issues source; the source is skipped when gh is unavailable

Steps

1. Run Orchestrator

python3 <agent-skills-dir>/bug-scrub/scripts/main.py \
  --source <sources-or-omit-for-all> \
  --severity <level> \
  --project-dir <path> \
  --out-dir docs/bug-scrub \
  --format both

2. Review Report

The orchestrator produces:

• docs/bug-scrub/bug-scrub-report.md — human-readable prioritized report
• docs/bug-scrub/bug-scrub-report.json — machine-readable for /fix-scrub
• docs/bug-scrub/bug-scrub-candidate-work.json — canonical candidate-work stubs for downstream prioritization; a successful clean run writes []

The Markdown report lists every open GitHub issue with its number, title, URL, and labels. The JSON report stores the same list in the github-issues source result's inventory. Issue inventory entries do not become findings or candidate-work stubs; the supervisor's candidate store is limited to 20 and a repository may have many more open issues. Review the inventory when choosing work to propose.

3. Interpret Results

Signal Sources:

• pytest: Test failures (severity: high)
• ruff: Lint violations (severity: high for errors, medium for warnings)
• mypy: Type errors (severity: medium)
• openspec: Spec validation issues (severity: medium)
• architecture: Diagnostics from architecture analysis (severity: mapped from report)
• security: Findings from security review report (severity: preserved from scanner)
• deferred: Uncompleted tasks and deferred findings from OpenSpec changes (severity: medium for active, low for archived)
• markers: TODO/FIXME/HACK/XXX in Python files (severity: medium for FIXME/HACK, low for TODO/XXX)
• github-issues: All open issues are listed in the issue inventory. GitHub CLI errors are recorded as source errors, and listings at the 1,000-issue limit fail rather than silently truncate.

Severity Levels (descending): critical > high > medium > low > info

Staleness Warnings: Reports older than 7 days trigger a refresh recommendation.

4. Next Steps

• Quick fixes: Run /fix-scrub --tier auto for tool-native auto-fixes (ruff)
• Guided fixes: Run /fix-scrub for auto + agent-assisted fixes
• Preview: Run /fix-scrub --dry-run to see what would be fixed
• Selective: Run /fix-scrub --severity high for high-priority items only
• Feature work: Create a /plan-feature proposal for findings that need design decisions

Quality Checks

python3 -m pytest <agent-skills-dir>/bug-scrub/tests -q

Common Rationalizations

Rationalization	Why it's wrong
"CI is green, so a bug-scrub is unnecessary"	CI runs only the configured checks at the configured strictness. Bug-scrub aggregates signals CI does not surface — deferred OpenSpec tasks, code markers, stale architecture diagnostics, security-report findings.
"I'll skip mypy/ruff because the project doesn't enforce them"	The collectors skip unavailable tools by design; running them surfaces latent issues even on projects that do not gate on them. The cost is one command.
"The report from last week is fine"	The skill's staleness logic flags reports older than 7 days for a reason — code drifts, deferred lists grow, new TODOs land daily. A stale report under-reports current debt.
"I'll just look at high-severity findings"	High-severity findings are loud but rarely the root cause; clusters of medium-severity findings in one hotspot file usually signal the deeper structural problem. Filter only after reading the hotspot summary.

Red Flags

• A bug-scrub-report.json older than 7 days being used as input to /plan-feature or /fix-scrub without a refresh — staleness warning was ignored.
• A report that shows zero findings from pytest, ruff, AND mypy simultaneously — almost certainly the collectors did not actually execute (missing tools, wrong project-dir).
• The deferred source returns zero entries on a project with multiple active OpenSpec changes — the OpenSpec CLI was not on the PATH or --project-dir pointed outside the repo.
• A planning session referencing "the bug-scrub report" without anyone able to produce the file path — the report exists only in chat, not on disk.

Verification

1. Confirm the report was generated within the last 7 days: stat -c %y docs/bug-scrub/bug-scrub-report.json (or equivalent) returns a recent timestamp.
2. Confirm at least three sources contributed findings (the report's sources field has length ≥ 3) — a single-source report is incomplete.
3. Confirm the report path was cited (with file path and severity filter) in any downstream plan or fix-scrub invocation that claims to act on it.
4. Confirm the markers source was not trivially empty: a non-trivial codebase with zero TODO/FIXME/HACK/XXX is suspicious; either the markers collector was disabled or --project-dir was wrong.