### 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 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: <RULE>` 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:
`<ruff_cmd> 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 `<ruff_cmd> format` before the next `<ruff_cmd> 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.
SynapticSkills