From b3d83370019acbf9d8cffef9780e8041a456f17c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 28 Aug 2026 09:30:37 +0800 Subject: [PATCH] =?UTF-8?q?feat(comment-cleanup):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E8=A8=BB=E8=A7=A3=E6=B8=85=E7=90=86=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- skills/comment-cleanup/SKILL.md | 33 +++++++++++++++++++++++++++++++++ 4 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 skills/comment-cleanup/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9d93fdf..2f669f1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e7b88cd..8a20ebb 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 8bfae14..c33b90e 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills/" } diff --git a/skills/comment-cleanup/SKILL.md b/skills/comment-cleanup/SKILL.md new file mode 100644 index 0000000..96239d2 --- /dev/null +++ b/skills/comment-cleanup/SKILL.md @@ -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.