# Fix Scrub

> Remediate findings from bug-scrub report — auto-fixes, agent-assisted fixes, and quality verification

- Skill: `jankneumann/fix-scrub` (Agent Skill, multi-file: 22 files)
- Install (CLI): `npx skillmds@latest add jankneumann/fix-scrub`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jankneumann/fix-scrub/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jankneumann (https://skillmd.com/u/jankneumann)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jankneumann/fix-scrub

---


# Fix Scrub

Consume the bug-scrub report and apply fixes with clean separation from the diagnostic phase. Classifies findings into three tiers (auto/agent/manual), applies fixes, verifies quality, and commits.

## Arguments

`$ARGUMENTS` - Optional flags:
- `--report <path>` (default: `docs/bug-scrub/bug-scrub-report.json`)
- `--tier <list>` (comma-separated; default: `auto,agent`; values: `auto`, `agent`, `manual`)
- `--severity <level>` (minimum severity; default: `medium`)
- `--dry-run` (plan fixes without applying — skips branch creation)
- `--max-agent-fixes <N>` (default: 10)
- `--worktree` (create an isolated git worktree for the fix-scrub branch; auto-enabled when running inside an existing worktree)

## Script Location

Scripts live in `<agent-skills-dir>/fix-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

- Bug-scrub report must exist (run `/bug-scrub` first)
- Python 3.11+
- ruff for auto-fixes

## Steps

### 0. Branch Setup

Skip this step if `--dry-run` is active.

Create an isolated branch for fix-scrub changes. All fixes go through PR review before reaching main.

```bash
# Pull latest main
git checkout main
git pull origin main

# Determine branch name (date-based, with collision suffix)
BRANCH_DATE=$(date +%Y-%m-%d)
BRANCH_NAME="fix-scrub/${BRANCH_DATE}"
SUFFIX=1
while git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; do
  SUFFIX=$((SUFFIX + 1))
  BRANCH_NAME="fix-scrub/${BRANCH_DATE}-${SUFFIX}"
done

# Create and switch to the fix-scrub branch
git checkout -b "$BRANCH_NAME"
echo "Created branch: $BRANCH_NAME"
```

#### Optional: Worktree Isolation

Create a worktree when `--worktree` is passed **or** when already inside a git worktree (auto-detection). This prevents fix-scrub from modifying an active implementation worktree.

```bash
# Detect if worktree isolation is needed
eval "$(python3 "<skill-base-dir>/../worktree/scripts/worktree.py" detect)"

if [[ "$IN_WORKTREE" == "true" ]] || [[ "<--worktree flag passed>" == "true" ]]; then
  # Agent-id for worktree disambiguation
  FIX_AGENT_ID="${AGENT_ID:-fix-$(date +%s)}"

  # Setup fix-scrub worktree (creates .git-worktrees/fix-scrub/<agent-id>/)
  eval "$(python3 "<skill-base-dir>/../worktree/scripts/worktree.py" setup "${BRANCH_DATE}" --branch "${BRANCH_NAME}" --prefix fix-scrub --agent-id "${FIX_AGENT_ID}")"
  cd "$WORKTREE_PATH"
  echo "Working directory: $(pwd)"
fi
```

After the fix-scrub is complete and changes are pushed, tear down the worktree:

```bash
# Teardown fix-scrub worktree
python3 "<skill-base-dir>/../worktree/scripts/worktree.py" teardown "${BRANCH_DATE}" --prefix fix-scrub --agent-id "${FIX_AGENT_ID}"
```

### 1. Load Report and Classify

```bash
python3 <agent-skills-dir>/fix-scrub/scripts/main.py \
  --report <report-path> \
  --tier <tiers> \
  --severity <level> \
  --dry-run
```

Review the dry-run output before applying.

### 2. Apply Fixes

```bash
python3 <agent-skills-dir>/fix-scrub/scripts/main.py \
  --report <report-path> \
  --tier <tiers> \
  --severity <level> \
  --max-agent-fixes <N>
```

This will:
1. Apply auto-fixes (ruff --fix)
2. Generate agent-fix prompts to `docs/bug-scrub/agent-fix-prompts.json`
3. Track OpenSpec task completions

### 3. Dispatch Agent Fixes (if applicable)

If agent-fix prompts were generated, resolve the implementer archetype and dispatch as parallel Task() agents:

```python
import json
import sys
from pathlib import Path

bridge_scripts = Path("<skill-base-dir>").parent / "coordination-bridge" / "scripts"
sys.path.insert(0, str(bridge_scripts))
import coordination_bridge

resolved = coordination_bridge.try_resolve_archetype_for_phase("IMPL_FIX", {})
resolved_model = resolved["model"] if resolved else None

with open("docs/bug-scrub/agent-fix-prompts.json") as f:
    prompts = json.load(f)

# Launch parallel agents — one per file group
for entry in prompts:
    Task(
        subagent_type="general-purpose",
        model=resolved_model,  # archetype: implementer (sonnet, or opus if escalated)
        description=f"Fix issues in {entry['file']}",
        prompt=entry["prompt"],
        run_in_background=True,
    )
```

Wait for all agents to complete, then verify.

### 4. Quality Verification

After all fixes (auto + agent) are applied, the orchestrator runs pytest, mypy, ruff, and openspec validate. If regressions are detected, review before committing.

### 5. Commit

```bash
git add .
git commit -m "$(cat <<'EOF'
fix(scrub): apply <N> fixes from bug-scrub report

Auto-fixes: <count> (ruff)
Agent-fixes: <count> (mypy, markers, deferred)
Manual-only: <count> (reported, not fixed)

Source report: <report-path>

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
```

### 6. Push and Create PR

Skip if no fixes were applied (dry-run or all findings were manual-only).

```bash
# Push the fix-scrub branch
git push -u origin "$BRANCH_NAME"

# Create PR with fix-scrub report as body
gh pr create \
  --title "fix(scrub): apply fixes from bug-scrub report $(date +%Y-%m-%d)" \
  --body "$(cat <<'EOF'
## Summary

Automated fix-scrub remediation from bug-scrub report.

### Fix Summary
<!-- Paste from docs/bug-scrub/fix-scrub-report.md -->
- Auto-fixes: <count> (ruff)
- Agent-fixes: <count> (mypy, markers, deferred)
- Manual-only: <count> (reported, not fixed)

### Quality Checks
- [ ] pytest passing
- [ ] mypy passing
- [ ] ruff passing
- [ ] openspec validate passing

Source report: `docs/bug-scrub/bug-scrub-report.json`

---
🤖 Generated with Claude Code
EOF
)"
```

### 7. Review Summary

Check `docs/bug-scrub/fix-scrub-report.md` for the full summary including:
- Fixes applied by tier
- Files changed
- OpenSpec tasks marked as completed
- Quality check results
- Manual action items requiring human attention

## Fixability Tiers

| Tier | Criteria | Action |
|------|----------|--------|
| **auto** | ruff with fixable rules | `ruff check --fix` |
| **agent** | mypy type errors, markers with 10+ chars context, deferred items with proposed fix | Task() agent with file scope |
| **manual** | architecture, security, deferred without fix, markers with insufficient context | Reported only |

## Quality Checks

```bash
python3 -m pytest <agent-skills-dir>/fix-scrub/tests -q
```