feat(comment-cleanup): 新增註解清理技能

2026-08-28 09:30:37 +08:00
parent aaa0227464
commit b3d8337001
4 changed files with 36 additions and 3 deletions
@@ -0,0 +1,33 @@
+---
+name: comment-cleanup
+description: 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/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: 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 「無發現」.
+2. 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.
+3. 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.
+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. Completion condition: `git diff` shows comment-only or documentation-string-only edits.
+5. 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.
+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.