Add guidance for commenting auxiliary code changes in usethis-python-code-modify skill (#1517)

Copilot · nathanjmcdougall · web-flow · commit 5056e6ea2710 · 2026-03-25T15:45:33.000+13:00
* Initial plan * Update usethis-python-code-modify skill to encourage comments on auxiliary changes Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/4198eba0-3fd7-41fc-8a20-94cf78150bf9 --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
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.1"
+  version: "1.2"
 ---
 
 # Modifying Python code
@@ -42,6 +42,17 @@ When you modify code, check whether the change affects areas that are documented
 - **Conventions in CONTRIBUTING.md**: The "Conventions" section documents project-wide conventions (e.g. `plain_print` instead of `print`, branding rules). If your change introduces a new convention or modifies an existing one, update this section.
 - **README.md**: If your change adds, removes, or renames CLI commands or tool integrations, update `README.md` to reflect this.
 
+## Document auxiliary changes with comments
+
+When working on a task, you may discover pre-existing issues that need fixing but are not directly related to the main change. For example, a test might fail due to a latent bug or a missing argument unrelated to your feature. When you fix such an issue, always add a brief code comment explaining why the change was made.
+
+Without a comment, reviewers lack the context to understand why a seemingly unrelated change was included. A short comment prevents confusion during review and preserves the rationale for future readers.
+
+### Procedure
+
+1. If you make a code change that is auxiliary to your main task — i.e. it fixes a pre-existing or latent issue you encountered along the way — add a code comment at the point of the change explaining the reason.
+2. Keep the comment concise: one or two lines explaining the problem and why the fix is necessary.
+
 ## 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.
