bug-scrub

Files (26)

• SKILL.md
• aggregate.py · scripts/
• bug_candidate_work.py · scripts/
• collect_architecture.py · scripts/
• collect_deferred.py · scripts/
• collect_github_issues.py · scripts/
• collect_markers.py · scripts/
• collect_mypy.py · scripts/
• collect_openspec.py · scripts/
• collect_pytest.py · scripts/
• collect_ruff.py · scripts/
• collect_security.py · scripts/
• main.py · scripts/
• models.py · scripts/
• parallel_runner.py · scripts/
• render_report.py · scripts/
• test_aggregate.py · tests/
• test_candidate_work.py · tests/
• test_collect_ci.py · tests/
• test_collect_deferred.py · tests/
• test_collect_github_issues.py · tests/
• test_collect_markers.py · tests/
• test_collect_reports.py · tests/
• test_models.py · tests/
• test_parallel_runner.py · tests/
• test_render_report.py · tests/

SKILL.md (first lines)

# 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

```bash
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

```bash
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.

From jankneumann/agentic-coding-tools, MIT.

More from jankneumann/agentic-coding-tools