From a3c480d91e21ab45e21eae66cdd0fb13ca8f069c Mon Sep 17 00:00:00 2001 From: Andrew Nester Date: Wed, 11 Nov 2026 14:04:14 +0000 Subject: [PATCH] pr-review skill: list doc comments in Python, shell and YAML too Pass 8 only grepped Go files, so for YAML, Python, script and test-only changes the doc-comment table came up empty on exactly the changes where the comment was the point. Also ask the reviewer to check other callers when a new comment claims an API quirk. Co-authored-by: Isaac --- .agents/skills/pr-review/SKILL.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/.agents/skills/pr-review/SKILL.md b/.agents/skills/pr-review/SKILL.md index 397ea485a14..3112e9c20ac 100644 --- a/.agents/skills/pr-review/SKILL.md +++ b/.agents/skills/pr-review/SKILL.md @@ -114,19 +114,27 @@ on code the change adds or modifies, not on pre-existing issues next to it. (often: an error, not a silent fallback). Table: `value (line) | written when | updated when | read by | can it disagree with the source of truth, and what happens then?` -8. **Every new doc comment.** List them: +8. **Every new doc comment.** List them. For Go: ```bash git diff "$BASE" "$TARGET" -- '*.go' ':!*_test.go' | grep -E '^\+(//|func |type |var |const )' ``` + `.agents/rules/comments.md` applies to Python, shell and YAML as well, so + when the change touches those, list their added comments the same way + (`'*.py'` with `^\+(#|def |class )`, `'*.sh'` and `'*.yml'` with `^\+#`). + Docstrings and `--help` text in `acceptance/bin/*.py` count, and so does + the doc comment of a new test function when the change is test-only; + otherwise those passes come up empty for exactly the changes where the + comment is the point. Each comment above a new top-level declaration goes in the table. It should say what is decided, from which input, and where the result comes from. Flag comments that are wrong, that blur similar nouns, or that describe the mechanism but not the intent. Offer the sharper sentence. Also look for code that works around surprising behavior of an API or tool (adds a suffix, strips a prefix, retries a specific error) without - a comment saying why; ask why it happens. + a comment saying why; ask why it happens. When a new comment states such + a quirk, check that the other callers of the same API agree with it. Table: `line | what the comment claims | what the code does | precise enough?` 9. **Tests.** Review test code as carefully as the code under test.