3.2 KiB
3.2 KiB
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
- User asks to clean comments: examples include "clean the comments", "remove review traces", or "do not leave review artifacts".
- Before commit:
jsc-hooksreports comment scope warnings, or a changed comment clearly carries process-only details. - 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/comment-scope.shblocks pattern-detectable violations after writes.jsc-review:code-reviewgroup 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
- Define the scope: inspect the current diff and list only added or modified comment lines. Include untouched legacy comments only when the user explicitly requested that. Completion condition: the cleanup scope is listed by file, or the run ends with the literal 「無發現」.
- Compare each scoped comment with
references/comment-scope.md. Remove process-only details and keep the real reason for the code. If a whole comment is only process detail and no real reason remains, delete the whole comment. Completion condition: every scoped comment is either unchanged with a reason, rewritten, or deleted. - Re-read the changed area after every rewrite. Confirm the sentence is complete, the logic still reads naturally, and no dangling fragment remains after deletion. Completion condition: every touched comment reads as a complete explanation or is gone.
- 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. Completion condition:
git diffshows comment-only or documentation-string-only edits. - Run the smallest relevant build or test command for the changed project. If no project command is available, run syntax checks for touched scripts and report the gap. Completion condition: verification passed, or the exact missing command is reported.
- 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.