jankneumann 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)
Valid sources: pytest, ruff, mypy, openspec, architecture, security, deferred, markers
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
openspecsource
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 reportdocs/bug-scrub/bug-scrub-report.json— machine-readable for/fix-scrub
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)
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 autofor tool-native auto-fixes (ruff) - Guided fixes: Run
/fix-scrubfor auto + agent-assisted fixes - Preview: Run
/fix-scrub --dry-runto see what would be fixed - Selective: Run
/fix-scrub --severity highfor high-priority items only - Feature work: Create a
/plan-featureproposal 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.jsonolder than 7 days being used as input to/plan-featureor/fix-scrubwithout a refresh — staleness warning was ignored. - A report that shows zero findings from
pytest,ruff, ANDmypysimultaneously — almost certainly the collectors did not actually execute (missing tools, wrong project-dir). - The
deferredsource returns zero entries on a project with multiple active OpenSpec changes — the OpenSpec CLI was not on the PATH or--project-dirpointed 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
- 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. - Confirm at least three sources contributed findings (the report's
sourcesfield has length ≥ 3) — a single-source report is incomplete. - 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.
- 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-dirwas wrong.