| name | fix-review-comments |
| description | Apply every comment-hygiene finding from the pre-PR review sentinel, then
refresh the sentinel. Use this after `/repo-review-full-no-comments` reports
comment-hygiene BLOCK/WARN findings or any time you want the comment/docstring
findings in the latest review applied in one pass. Reads the sentinel written by
`agent/_shared/review_sentinel.py`; pairs with the `comment-hygiene` skill
for the checklist and rewrite rules. |
fix-review-comments — Apply Comment-Hygiene Findings From the Sentinel
/repo-review-full-no-comments writes a rendered review to a sentinel file
keyed by HEAD's SHA. This skill drains its [comment-hygiene:warn] and
[comment-hygiene:block] findings: apply each rewrite, commit, then re-review
so the refreshed sentinel is clean. The retained pre-pr-review-gate.sh can
consume that sentinel after its local registration is restored.
The fix is an apply step, not a re-judgment. Consistency comes from
applying the rewrite the review already produced — not from re-deriving one.
You MUST complete every step in order.
Step 1: Locate and read the sentinel
REVIEW_PATH=$(python3 agent/_shared/review_sentinel.py path "$(git rev-parse HEAD)")
test -f "$REVIEW_PATH" || echo "MISSING: $REVIEW_PATH"
If the file is missing, the review hasn't run against this HEAD. Stop and tell
the user to run /repo-review-full-no-comments first — do not fabricate one.
Read the whole sentinel. The findings you act on are the lines tagged
**[comment-hygiene:warn]** or **[comment-hygiene:block]**, grouped under
their ### \`` headers. Ignore every other skill's findings — they are
out of scope here. [comment-hygiene:nit] bullets live in the sentinel's
## Nits section and are also out of scope: they gate nothing, so applying them
would spend a commit on a preference the author never opted into. Apply a NIT
only when the user names it.
Step 2: Extract one work-item per comment-hygiene finding
For each tagged finding, capture:
path and line (from the **L<line>** anchor and its ### \`` header).- The C-id (
C1–C12) named in the description.
- The verbatim
Before: / After: rewrite if the body carried one. The
review preserves code fences, so most findings ship their own rewrite.
When a finding's body is terse and carries no usable After:, read the cited
path:line (±2 lines) and derive the rewrite straight from the
comment-hygiene checklist for that C-id. This is the only place judgment
re-enters; keep it mechanical — apply the rule, don't re-litigate whether the
finding is valid.
Step 3: Bucket each finding — apply now vs. surface
| Bucket | C-ids | Action |
|---|
| Mechanical | C2, C3, C6, C7, C8, C9, C11 | Apply the rewrite (deletion or tightening) verbatim. |
| Move-in-place | C1 | Lift the comment above the - name: step. Surface if the move is non-obvious. |
| Needs a ref | C5, C10 | Apply only when a real issue/rationale is available (Step 4). Else surface. |
| Rewrite-ship | C12 | Apply the After: if present; else tighten per the doc-map rules. |
The mitigation that keeps the hard gate honest: never invent a placeholder
issue number to satisfy C5/C10. A fake # … — see #0 would pass both the
checklist pattern and the gate while baking wrong content into the code. If you
can't source a real ref, leave that one finding unfixed and report it — the
gate legitimately stays closed until a human supplies it (or sets
REVIEW_COMMENT_GATE=off for a genuinely intentional finding).
Step 4: Source a real issue ref for C5 / C10 (mitigation)
Before surfacing a needs-a-ref finding, try to find a real number already tied
to this work:
gh pr view --json body -q .body 2>/dev/null | grep -oE '(Refs|Closes|Fixes|Part of) #[0-9]+'
git log -1 --pretty=%B | grep -oE '#[0-9]+'
Use a number only if it actually governs this change (the PR's linked issue or
the commit's trailer). If nothing applies, do not guess — surface the finding.
Step 5: Apply the fixes — content-anchored, bottom-up
Findings are anchored to path:line, so editing top-down shifts every later
line in the same file. Apply per file, in descending line order, and match
on the verbatim Before: text (exact-match Edit), not on the line number.
Content-anchoring survives any drift the review's line numbers may already
have.
Do not touch code the findings don't cite. This skill changes inline text
only — comments, docstrings, YAML comments, doc-map.yaml prose.
Step 6: Commit the fixes
The re-review in Step 7 reads committed history (base..HEAD), so uncommitted
edits won't clear the findings. Commit the applied fixes:
git add -A
git commit -m "chore(comments): apply comment-hygiene fixes from pre-PR review"
Conventional-commit + gitlint rules apply (see /github-taxonomy for scope).
If these fixes belong with an unpushed WIP commit, squash them in instead of
adding a separate commit — your call based on whether the prior commit is
already pushed.
Step 7: Re-review to refresh the sentinel
Run /repo-review-full-no-comments again. It writes a fresh sentinel against
the new HEAD. This both regenerates the gate's contract at the current SHA and
re-reviews your fixes (a bad rewrite gets re-flagged here rather than shipping).
Step 8: Report
Summarize:
- Applied — count by C-id, with
path:line for each.
- Surfaced — every finding left unfixed and why (needs a real issue ref, a
rationale decision, or a non-obvious C1 move). These are what the user must
resolve before treating the sentinel as clean.
- Sentinel status — whether the refreshed sentinel is clean. If findings
remain, name each accepted finding and its rationale.
Notes
- This skill is the remediation half of the pre-PR review flow; the detection
half is
/repo-review-full-no-comments. Keep the retained gate parser in sync
because it greps for the [comment-hygiene:<severity>] tag after restoration.
- Rewrite semantics (what each C-id means, the
.. attribute :: and
no-:param self: pydoclint rules) live in the comment-hygiene skill. When
re-deriving a fix in Step 2, that skill is authoritative — do not reinvent the
rules here.
- Re-running is cheap relative to shipping wrong content. If a fix looks
ambiguous, surface it rather than guessing.
