--- title: "Ruff Recursive Fix: review, setup & limitations · Undominated.ai" canonical: https://undominated.ai/skills/github-ruff-recursive-fix/ description: "Enforces Python code quality with scoped Ruff runs: safe fixes first, unsafe fixes second with diff review each pass, then targeted manual remediation under explicit stop criteria." --- # Ruff Recursive Fix: review, setup & limitations · Undominated.ai > Enforces Python code quality with scoped Ruff runs: safe fixes first, unsafe fixes second with diff review each pass, then targeted manual remediation under explicit stop criteria. [← Explore all skills](/skills/) LANGUAGES AND TOOLING / GitHub community # Ruff Recursive Fix Enforces Python code quality with scoped Ruff runs: safe fixes first, unsafe fixes second with diff review each pass, then targeted manual remediation under explicit stop criteria. [See setup guidance ↓](#setup)[Original source ↗](https://github.com/github/awesome-copilot/tree/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix) SOURCE REVIEW Reviewed 2026-10-15 Evidence 6 linked sources Publisher GitHub community Licence [MIT ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/LICENSE) Revision 3a685010a7af [Read what was—and wasn’t—checked ↓](#review) “Run Ruff checks with optional scope and rule overrides, apply safe and unsafe autofixes iteratively, review each change, and resolve remaining findings with targeted edits or user decisions.” [GitHub community · upstream description ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md) Our analysis follows below. 01 / THE REASONING ## Why this made the selection. - Fix passes are ordered by blast radius: safe autofixes with diff review and formatting first, unsafe fixes only if findings remain, then minimal manual edits. - The loop cannot spin silently: every iteration ends in format plus check, progress stalls trigger a summary with options, and ambiguity always routes to the user. ### A good fit for - Cleaning a Python tree or folder to a scoped Ruff ruleset - Adjudicating remaining findings into fixes, narrow suppressions or user decisions - Turn a stalled Ruff remediation loop into a list of blocked rules and explicit decisions. ### Weigh up before choosing - Unsafe autofixes can change behavior; the workflow's value depends on actually performing its mandated diff reviews rather than waving them through. - Runner resolution assumes uv, Ruff, Python or an equivalent is present; rule choices still need project judgment since the skill accepts arbitrary select and ignore overrides. - The input default enables unsafe fixes; disabling them requires an explicit allow_unsafe_fixes setting or equivalent request. 02 / THE REVIEW RECORD ## What we actually inspected. Source review has boundaries. A clear record is more useful than a “safe” badge. ### Material inspected - skills/ruff-recursive-fix/SKILL.md - LICENSE - SKILL.md and LICENSE re-read at 3a685010 on 2026-10-13 for the downloadable definition; both byte-identical at HEAD 156736fb (git blob SHAs). - vercel-labs/skills@7407f3893ad4dceab546ac002c3ef806e4000c73:README.md ### Our findings - Command construction reuses one resolved runner for every check and format call, with worked examples for scoping and rule overrides. - Suppression requires all three conditions (rule conflict, disproportionate refactor, narrow scope) plus preferring rule-specific noqa with a reason comment. - The output contract reports scope, iterations, fixed and manual findings, suppressions with rationale, and remaining decisions. - Unsafe fixes default to enabled. The loop stops on repeated lack of progress and must then identify blocked rules, files and the options requiring a user choice. ### Not established by this review - No Ruff run was executed with this skill. - Fix-loop termination and suppression behavior were not observed on a live codebase. - Not executed: it was not installed or run. The review applies to the material and revision named here. A newer upstream release can change its behavior. 03 / PUT IT TO WORK ## Add a skill to your workflow. [Upstream setup instructions ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md) DOCUMENTED COMMAND npx skills add github/awesome-copilot/skills/ruff-recursive-fix --skill ruff-recursive-fix Copy command ↗ Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above. Optional: install the reviewed revision Keeps the original source and installer version where recorded, while leaving your AI tools and installation scope for you to choose. npx skills add https://github.com/github/awesome-copilot/tree/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix --skill ruff-recursive-fix Copy reviewed-revision command ↗ - Install the complete skill directory; select your AI tools and project or global scope. - Review the instructions before invoking them. The source revision shown here is the one reviewed; the installer was not executed or version-pinned by this review. - For manual installation instead, download the complete bundle from https://undominated.ai/resources/skills/github-ruff-recursive-fix/bundle.zip and extract it into a new directory. It holds SKILL.md unchanged at revision 3a685010, the upstream licence and an attribution file. - Place the extracted directory in your host's documented skills directory, named ruff-recursive-fix. Keep SKILL.md and the licence together. ### Before you start - Node.js/npm and git for the documented Skills installer - An agent host that supports the skill format and running Ruff commands - A Python project with Ruff installed and permission to edit flagged files ### Compatibility Agent Skills-compatible coding agents · Python projects with Ruff reachable through uv, PATH, python -m or an equivalent ### Repository lint and edit loop - Run Ruff check, fix and format commands in the chosen scope - Edit flagged Python files and add narrow suppressions when justified - Autofixes rewrite source files; review diffs before accepting ### Cost model The skill is MIT-licensed; agent calls and local compute remain separate. THE COMPLETE REVIEWED DEFINITION ## Read it before you reuse it. Original source bytes, with attribution. Review the host-specific setup notes above. Copy definition ↗ [Download definition + licence ↗](/resources/skills/github-ruff-recursive-fix/bundle.zip)[Raw Markdown ↗](/resources/skills/github-ruff-recursive-fix/definition.md) --- name: ruff-recursive-fix description: Run Ruff checks with optional scope and rule overrides, apply safe and unsafe autofixes iteratively, review each change, and resolve remaining findings with targeted edits or user decisions. --- # 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: ```bash check ``` Formatter command: ```bash format ``` With optional target: ```bash format ``` Add optional target: ```bash check ``` Add optional overrides as needed: ```bash --select --ignore --extend-select --extend-ignore ``` Examples: ```bash # 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 ` 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 ` format` on the same scope. 4. Re-run ` 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 ` format` on the same scope. 4. Re-run ` 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 ` format` on the same scope. 4. Re-run ` 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 all conditions are true: - The rule conflicts with required behavior, public API, framework conventions, or readability goals. - Refactoring would be disproportionate to the value of the rule. - The suppression is narrow and specific (single line, explicit code when possible). Guidelines: - Prefer `# noqa: ` over broad `# noqa`. - Add a brief reason comment for non-obvious suppressions. - If two or more valid outcomes exist, always ask the user which option to prefer. ### 7. Recursive Loop and Stop Criteria Repeat steps 2 to 6 until one of these outcomes: - ` check` returns clean. - Remaining findings require architectural/product decisions. - Remaining findings are intentionally suppressed with documented rationale. - Repeated loop makes no progress. Each loop iteration must include ` format` before the next ` check`. When no progress is detected: 1. Summarize blocked rules and affected files. 2. Present valid options and trade-offs. 3. Ask the user to choose. ## Quality Gates Before declaring completion: - Ruff returns no unexpected findings for the chosen scope/options. - All autofix diffs are reviewed for correctness. - No suppression is added without explicit justification. - Any unsafe fix with possible behavioral impact is highlighted to the user. - Ruff formatting is executed in every iteration. ## Output Contract At the end of execution, report: - Scope and Ruff options used. - Number of iterations performed. - Summary of fixed findings. - List of manual fixes. - List of suppressions with rationale. - Remaining findings, if any, and required user decisions. ## Suggested Prompt Starters - "Run ruff-recursive-fix on the whole repo with default config." - "Run ruff-recursive-fix only on src/models, ignore DOC rules." - "Run ruff-recursive-fix on tests with select F,E9,I and no unsafe fixes." - "Run ruff-recursive-fix on src/data and ask me before adding any noqa." The download contains SKILL.md . Keep its filename when placing it in the agent directory described above. By **GitHub community**. [Exact upstream source ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md) · [Licence](/resources/skills/github-ruff-recursive-fix/LICENSE.txt) · [Attribution](/resources/skills/github-ruff-recursive-fix/ATTRIBUTION.txt) SHA-256 92151e328fbccab628de9496797fce39636555e65dd7434687751673b4b57f8c Read the applicable licence MIT License Copyright GitHub, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 04 / FOLLOW THE EVIDENCE ## The source trail. Our notes are separate from the original resource. Check upstream before adopting a new version. - [Skill definition at reviewed revision ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md Supports: summary, upstreamDescription, whySelected, bestFor, limitations, review, compatibility, access - [Upstream license or licensing declaration ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/LICENSE) Checked 2026-10-13 https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/LICENSE Supports: license - [Publisher installation and project documentation ↗](https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/README.md) Checked 2026-10-07 https://github.com/github/awesome-copilot/blob/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/README.md Supports: install, compatibility, access - [Skills installer source formats and selective installation ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md) Checked 2026-10-07 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/README.md Supports: install - [Installer implementation: full commit SHA fallback ↗](https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts) Checked 2026-10-07 https://github.com/vercel-labs/skills/blob/7407f3893ad4dceab546ac002c3ef806e4000c73/src/git.ts Supports: install - [Pinned continuation review W30 ↗](https://raw.githubusercontent.com/github/awesome-copilot/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md) Checked 2026-10-15 https://raw.githubusercontent.com/github/awesome-copilot/3a685010a7afdc0dbd4c83b7fbda6c316aa516e5/skills/ruff-recursive-fix/SKILL.md Supports: review.findings, bestFor, limitations KEEP COMPARING ## Other approaches to consider. Related by category or shared topics. These are alternatives to inspect, not a measured quality order. [### .NET Timezone ↗ Resolves .NET timezone work through the right library first — TimeZoneConverter for cross-platform, NodaTime for recurring schedules and strict DST arithmetic — and ships both Windows and IANA identifiers on every answer, seven copy-paste code patterns, and the pitfall list from DateTimeKind.Unspecified to DST transitions that skip or repeat local times.](/skills/github-dotnet-timezone/)[### Trail of Bits Modern C++ ↗ Pushes new C++ toward C++20, 23, and 26 idioms and a hardened libc++, and stops when the user requires an older standard or the file is C.](/skills/trailofbits-modern-cpp/)[### Turborepo ↗ Monorepo build-system discipline for Turborepo: package tasks instead of root tasks, turbo.json task registration, cache outputs and hashing inputs, environment variables as cache keys, --affected runs, CI setup, and tag-based package boundaries.](/skills/jetbrains-turborepo/) [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/) ## Continue your investigation - [Choose a toolkit](/tools/) - [Inspect execution hosts](/agents/) - [Check tool access](/mcp-servers/) - [Check project dependencies](/check-repo/)