Ruff-Recursive-Fix

# Ruff Recursive Fix

Overview

Use this skill to enforce code quality with Ruff in a controlled, iterative workflow.

It supports:

- Optional scope limitation to a specific folder.

- Default project settings from `pyproject.toml`.

- Flexible Ruff invocation (`uv`, direct `ruff`, `python -m ruff`, or equivalent).

- Optional per-run rule overrides (`--select`, `--ignore`, `--extend-select`, `--extend-ignore`).

- Automatic safe then unsafe autofixes.

- Diff review after each fix pass.

- Recursive repetition until findings are resolved or require a decision.

- Judicious use of inline `# noqa` only when suppression is justified.

Inputs

Collect these inputs before running:

- `target_path` (optional): folder or file to check. Empty means whole repository.

- `ruff_runner` (optional): explicit Ruff command prefix (for example `uv run`, `ruff`, `python -m ruff`, `pipx run ruff`).

- `rules_select` (optional): comma-separated rule codes to enforce.

- `rules_ignore` (optional): comma-separated rule codes to ignore.

- `extend_select` (optional): extra rules to add without replacing configured defaults.

- `extend_ignore` (optional): extra ignored rules without replacing configured defaults.

- `allow_unsafe_fixes` (default: true): whether to run Ruff unsafe fixes.

- `ask_on_ambiguity` (default: true): always ask the user when multiple valid choices exist.

Command Construction

Build Ruff commands from inputs.

0. Resolve Ruff Runner

Determine a reusable `ruff_cmd` prefix before building commands.

Resolution order:

1. If `ruff_runner` is provided, use it as-is.

2. Else if `uv` is available and Ruff is managed through `uv`, use `uv run ruff`.

3. Else if `ruff` is available on `PATH`, use `ruff`.

4. Else if Python is available and Ruff is installed in that environment, use `python -m ruff`.

5. Else use any project-specific equivalent that invokes installed Ruff (for example `pipx run ruff`), or stop and ask the user.

Use the same resolved `ruff_cmd` for all `check` and `format` commands in the workflow.

Base command:

<ruff_cmd> check

Formatter command:

<ruff_cmd> format

With optional target:

<ruff_cmd> format <target_path>

Add optional target:

<ruff_cmd> check <target_path>

Add optional overrides as needed:

--select <codes>
--ignore <codes>
--extend-select <codes>
--extend-ignore <codes>

Examples:

# Full project with defaults from pyproject.toml
ruff check

# One folder with defaults
python -m ruff check src/models

# Override to skip docs and TODO-like rules for this run
uv run ruff check src --extend-ignore D,TD

# Check only selected rules in a folder
ruff check src/data --select F,E9,I

Workflow

1. Baseline Analysis

1. Run `<ruff_cmd> check` with the selected scope and options.

2. Classify findings by type:

- Autofixable safe.

- Autofixable unsafe.

- Not autofixable.

3. If no findings remain, stop.

2. Safe Autofix Pass

1. Run Ruff with `--fix` using the same scope/options.

2. Review resulting diff carefully for semantic correctness and style consistency.

3. Run `<ruff_cmd> format` on the same scope.

4. Re-run `<ruff_cmd> check` to refresh remaining findings.

3. Unsafe Autofix Pass

Run only if findings remain and `allow_unsafe_fixes=true`.

1. Run Ruff with `--fix --unsafe-fixes` using the same scope/options.

2. Review resulting diff carefully, prioritizing behavior-sensitive edits.

3. Run `<ruff_cmd> format` on the same scope.

4. Re-run `<ruff_cmd> check`.

4. Manual Remediation Pass

For remaining findings:

1. Fix directly in code when there is a clear, safe correction.

2. Keep edits minimal and local.

3. Run `<ruff_cmd> format` on the same scope.

4. Re-run `<ruff_cmd> check`.

5. Ambiguity Policy

If there are multiple valid solutions at any step, always ask the user before proceeding.

Do not choose silently between equivalent options.

6. Suppression Decision (`# noqa`)

Use suppression only when a