review/skills/comment-cleanup/SKILL.md

name, description

name

description

comment-cleanup

Clean review traces and document-tracking noise from comments touched by the current change. Use when the user asks to clean comments, remove review traces, or when a pre-commit check finds process details in changed comments. It rewrites comments only, keeps code behavior unchanged, and uses references/comment-scope.md as the single source of banned and allowed content. Do not use for untouched legacy comments unless the user explicitly asks for that wider scope.

comment-cleanup

Clean comments changed in the current diff so they explain why the code exists, without carrying review traces, issue coordinates, wiki page ids, or other process-only details.

When to run

1. User asks to clean comments: examples include "clean the comments", "remove review traces", or "do not leave review artifacts".
2. Before commit: jsc-hooks reports comment scope warnings, or a changed comment clearly carries process-only details.
3. Not for untouched legacy comments: only widen the scope when the user explicitly asks for legacy cleanup.

Single Source

Use references/comment-scope.md for the banned list, allowed list, and rewrite rules. Do not copy those lists into this skill.

Division of Labor

• jsc-hooks/hooks/comment-scope.sh blocks pattern-detectable violations after writes.
• jsc-review:code-review group 2 reports judgment-based cases that patterns cannot decide.
• This skill cleans the changed comments. Do not report the same finding again when a hook or code review already reported it; either clean it or explain why it is outside this skill's scope.

Steps

1. Define the scope with tools/changed-comments.sh, run from the repository being cleaned: no argument for uncommitted work, tools/changed-comments.sh {base} when an implementation is complete and the base branch is the comparison point. It prints one row per changed comment line — file, line number, content — so this step never judges by eye which lines are comments; that judgment lives in the script, next to the one jsc-hooks/hooks/comment-scope.sh already uses. Read its exit code: 0 its stdout is the cleanup scope, and step 2 hands each file its own rows; 1 this change added or modified no comment line, so report the literal 「無發現」 and stop, spawn no sub agent; 2 a parameter or environment error, so report the script's stderr verbatim and stop, spawn no sub agent, and never substitute a hand-read diff — a scope that could not be computed is not an empty scope. Widen to untouched legacy comments only when the user explicitly asked for that, and say so in the report. Completion condition: the cleanup scope is listed by file, or the run ended with 「無發現」 or with the script's error.

2. Rewrite one file per sub agent, and every file MUST run as a sub agent. One file's comments never depend on another file's, so the sub agents run in parallel. Each sub agent is handed one file path and that file's scoped comment lines from step 1, and it compares each of them with references/comment-scope.md, removes process-only details, and keeps the real reason for the code. A comment that is only process detail with no real reason left is deleted whole. Each sub agent returns the file path, the categories it removed, and the line numbers it touched. Completion condition: every file's sub agent has returned, and every scoped comment is either unchanged with a stated reason, rewritten, or deleted.

3. Each sub agent re-reads its own changed area before it returns. It confirms every sentence is complete, the logic still reads naturally, and no dangling fragment remains after a deletion; a fragment it cannot resolve is reported instead of left behind. Completion condition: every sub agent has confirmed its file, and no returned report names an unresolved fragment.

4. Change comments and documentation strings only. Do not change executable behavior, identifiers, control flow, data shape, or tests except when a test fixture literally asserts the old comment text. jsc-hooks/hooks/write-guard.sh in review mode is the code-level backstop, but it covers this skill only as far as jsc-hooks can decide a comment line precisely: where that decision is not precise, the guard is limited to jsc-review:code-review and jsc-review:api-doc, which write nothing at all, and this skill runs unguarded. Only claude has a PreToolUse hook in the first place, so on codex, copilot, antigravity, and kiro this step's prose is the only constraint. Completion condition: git diff shows comment-only or documentation-string-only edits.

5. Run the smallest relevant build or test command once for the whole changed project, after every sub agent in step 2 has returned. Read the exit code. 0 — verification passed. Non-zero — the command ran and failed, so name the command, its exit code, and the failing output, then decide whether this run caused it: a failure that names a file this run touched is treated as caused here, so restore that file's comment syntax and re-run the command once; if it fails the same way again, revert this run's edits in that file and report the revert. A failure that names no file this run touched is reported as pre-existing, and the cleanup edits stay. If no project command is available, run syntax checks for the touched scripts and report the gap. Completion condition: the command exited 0, or the report states the command, its exit code and whether the failure belongs to this run, or the exact missing command is reported.

6. Report the cleanup by category, not by full diff. Completion condition: the report names which categories were removed, which files were touched, and whether verification passed.

7. Record how this run ended, as the very last thing this skill does — after the verification of step 5, whose result decides most of the status below:

   jsc-hooks/tools/report-status.sh skill-end jsc-review:comment-cleanup {status} {exit} "{detail}"

   Resolve that path the way this file already names jsc-hooks/hooks/comment-scope.sh — the sibling plugin directory, no separate lookup rule for this one call. A missing script is not a failure here: skip this step in silence and let the run end as it stands. The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. This is the one skill of the three that edits files, so the rule matters more here: rewritten comments are already on disk, and a recorder that is not installed must not turn that into a failed run.

   status	This skill's case
   ok	Every scoped comment is unchanged with a stated reason, rewritten, or deleted, no sub agent reported an unresolved fragment, and step 5's verification command exited 0
   blocked	changed-comments.sh exit 2 — a parameter or environment error left the scope uncomputed, so no file was read and none was rewritten. A scope that could not be computed is not an empty scope, and this status is what keeps the two apart
   degraded	The comments are cleaned but nothing confirmed them: no project build or test command exists so only syntax checks ran, or step 5 failed on a file this run never touched and the failure was recorded as pre-existing while the edits stayed. A sub agent that returned an unresolved fragment lands here too
   failed	Step 5 failed on a file this run touched, the one retry failed the same way, and this run's edits in that file were reverted. The cleanup did not stand, and the revert is the fact the caller has to see
   aborted	changed-comments.sh exit 1 — this change added or modified no comment line, so there is nothing to clean and no sub agent was spawned. The user asking to stop before step 2 lands here as well

   {exit} is the exit code of whatever decided the status, 0 for ok. {detail} is one short line well under 200 characters: file and comment-line counts plus exit codes, never comment text, file paths, branch names, or personal data — the text this skill removes is exactly the text that must not be copied into an event line.

   Completion condition: the command has run, or the script was absent and this step was skipped.