# Safe Bulk Cleanup

> Use when bulk-cleaning lint issues across a Python repo.

- Skill: `jajabong/safe-bulk-cleanup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jajabong/safe-bulk-cleanup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/safe-bulk-cleanup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jajabong (https://skillmd.com/u/jajabong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jajabong/safe-bulk-cleanup

---


# Safe Bulk Cleanup

Bulk lint fixes (ruff --fix, pyflakes) can silently break multi-line `from X import (a, b, c)` blocks when a name is re-exported by the source module. This skill prevents that.

## When to use

- `ruff check --fix` on a whole package
- Removing unused imports / unused variables across many files
- Any automated style cleanup that touches import statements

## Hard rules

1. **Never run `ruff --fix` on a whole package.** It rewrites multi-line import blocks and deletes re-exported names.
2. **Only fix single-line unused imports**, one file at a time, with `patch`.
3. **Before deleting any import, grep for re-exports:**
   ```bash
   grep -rn "from <module> import.*<name>" src/ --include="*.py"
   ```
   If ANY other module imports that name from the module you're editing, it's a re-export — keep it.
4. **Multi-line `from X import (a, b, c)` blocks: never auto-fix.** Only hand-edit if you've verified every name.
5. **After each file, run import check:**
   ```bash
   PYTHONPATH=src python -c "import <module>"
   ```
6. **After the batch, run the full test suite** — collection errors (ImportError) mean you broke a re-export.

## Workflow

1. Get the list: `ruff check src/ --select F401 --statistics`
2. For each file with F401:
   - `grep -n "import" <file>` to see the import block
   - For each unused name, check re-export: `grep -rn "from <file_module> import.*<name>" src/`
   - If no re-export, `patch` to remove the single-line import
   - If re-export exists, leave it (add `# noqa: F401` if it's intentional)
3. Verify: `PYTHONPATH=src python -c "import <module>"` per file
4. Full suite: `python -m pytest tests/ -q`

## Pitfalls

- **ruff --fix on multi-line import blocks** — deletes names that are re-exported, causing ImportError in downstream modules (collection errors in pytest)
- **F401 in `__init__.py`** — often intentional re-exports; never auto-fix
- **`# noqa` directives** — check they're valid before relying on them

## Verification

```bash
PYTHONPATH=src python -m pytest tests/ -q  # must be green
ruff check src/ --select F401 --statistics  # count should drop, not break
```