usethis-python · nathanjmcdougall · Mar 31, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 31, 2026
diff --git a/.agents/skills/usethis-python-code-modify/SKILL.md b/.agents/skills/usethis-python-code-modify/SKILL.md
@@ -4,7 +4,7 @@ description: Modify Python code (e.g. refactor, add new code, or delete code)
 compatibility: usethis, Python, pytest
 license: MIT
 metadata:
-  version: "1.3"
+  version: "1.4"
 ---
 
 # Modifying Python code
@@ -56,4 +56,4 @@ Without a comment, reviewers lack the context to understand why a seemingly unre
 
 ## Run static checks after finishing modifications
 
-After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging.
+After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging. You must fix **all** failures reported by the static checks, even pre-existing ones that are unrelated to your changes. CI enforces these checks on the entire codebase, so leaving any failure unfixed will block your PR.
diff --git a/.agents/skills/usethis-qa-static-checks/SKILL.md b/.agents/skills/usethis-qa-static-checks/SKILL.md
@@ -27,3 +27,11 @@ Before submitting changes for review, **always** run these static checks. This a
 **Important:** A prek run is a failure if it reports `Files were modified by following hooks`, even if every individual hook shows "Passed" or "Skipped". File modifications by hooks (e.g. auto-formatting by Ruff or prettier) count as a failure because the working tree was changed. You must re-run prek after such modifications to confirm a clean pass.
 
 It's quite common for minor cosmetic changes to be made automatically when running the prek checks, even by linters such as Ruff and mkdownlint-cli2. Since auto-fixes may have been applied during the first run, if checks fail, you should re-run a second time to see if any issues remain. Only then should you proceed to fix any remaining issues manually.
+
+## Fix all failures, including pre-existing ones
+
+When static checks report failures, you **must** fix all of them — not just those caused by your changes. This includes pre-existing failures that were already present before your PR. Do not skip or ignore a failure because it is "unrelated" to your task.
+
+**Why this matters:** CI enforces static checks on the entire codebase, not just changed files. If you leave pre-existing failures unfixed, CI will fail and your PR cannot be merged. Fixing these failures as you encounter them keeps the codebase healthy and avoids blocking your own work.
+
+If a pre-existing failure requires a fix that is outside the scope of your task (e.g. a large refactor), document the issue and create a GitHub issue to track it. But in most cases, pre-existing static check failures are minor and should be fixed in your PR.
diff --git a/AGENTS.md b/AGENTS.md
@@ -455,10 +455,7 @@ External skills can be installed if they are not present — see the `usethis-sk
 - ALWAYS consider the `usethis-python-test-full-coverage` to be relevant: if your task involves
   writing or modifying code, always use this skill to write tests and verify full coverage
   before finishing. Aim for 100% coverage on new or changed code.
-- ALWAYS consider the `usethis-qa-static-checks` to be relevant: before finishing your task,
-  always run this skill to check for any issues. This applies to ALL changes, including
-  documentation-only changes and skill file edits — static checks catch sync issues,
-  formatting problems, and other regressions that affect every file type.
+- ALWAYS consider the `usethis-qa-static-checks` to be relevant: if you think your task is complete, always run this skill to check for any issues before finishing. You must fix **all** static check failures, including pre-existing ones unrelated to your changes. This applies to ALL changes, including documentation-only changes and skill file edits — static checks catch sync issues, formatting problems, and other regressions that affect every file type. CI enforces checks on the entire codebase, so unfixed failures will block your PR.
 - ALWAYS mention which skills you've used after completing any task, in PR descriptions, and comments.
 - ALWAYS reference the relevant issue ID in PR descriptions using a closing keyword, e.g. `Resolves #123`. This ensures traceability between PRs and the issues they address.