branch-comment-cleanup
Strip unnecessary comments from the current branch's changes and make the code self-explanatory instead — renaming, extracting, and naming constants where a comment was propping up unclear code. Only business-logic and "why" comments survive. Use when the user wants to clean up comments, remove AI narration comments, make code self-documenting, or tidy a diff before opening a PR.
glrodasz · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add glrodasz/dotfiles --skill branch-comment-cleanup技能说明
name: branch-comment-cleanup description: > Strip unnecessary comments from the current branch's changes and make the code self-explanatory instead — renaming, extracting, and naming constants where a comment was propping up unclear code. Only business-logic and "why" comments survive. Use when the user wants to clean up comments, remove AI narration comments, make code self-documenting, or tidy a diff before opening a PR.
Branch Comment Cleanup
Remove comments the code should be saying itself, restricted to what this branch introduced. Where a comment exists because the code is unclear, fix the code — rename, extract, name the constant — rather than rewording the comment.
Mode: apply, then report. Make the edits, verify, and report. git diff is the review
surface. Ask before exported-API renames; list the rest under "Needs your call".
Hard rules (never violate)
- Only touch lines added or modified by this branch. Pre-existing comments and untouched files are off-limits, however bad they look. If you spot something worth fixing out of scope, mention it in the report — don't edit it.
- Behavior-preserving only. No logic changes, no reordering that could shift side effects.
- Renames must update every reference — LSP rename where available, otherwise exhaustive grep including string literals, dynamic keys, and test files. Never rename a public or exported API without asking.
- Repo conventions win. Before deleting any doc comment, check
CLAUDE.md/AGENTS.md, ESLint config (jsdoc/*,eslint-plugin-tsdoc, header rules), and whether the file's neighbors follow a documented style.
Phase 0 — Scope
- Detect the base branch:
git symbolic-ref refs/remotes/origin/HEAD; fall back tomain,master,develop. Ask if ambiguous. BASE=$(git merge-base HEAD <base>).git diff $BASE...HEAD -U0plusgit diff -U0andgit diff --cached -U0for uncommitted work —-U0gives the exact added-line ranges with no context bleed.- Build a per-file list of touched line ranges. Only comments inside those ranges are in scope.
- Record
git diff $BASE --name-onlyplusgit ls-files --others --exclude-standard(untracked files) now — Phase 3 compares against it.
Phase 1 — Classify every comment in scope
DELETE
- Restates the code:
// increment counter,// return the result - Step-by-step narration:
// First we…,// Now handle…,// Finally… - Section-divider banners inside a function
- JSDoc/docblocks that only repeat the signature, parameter names, or types the language already declares
- Commented-out code
- Changelog or attribution noise:
// added by,// new in v2,// updated - Comments explaining a diff to the reviewer rather than the code to a reader
KEEP
- Domain and business rules, especially with their source (
// VAT is 21% per EU rule X) - Non-obvious why: chosen trade-offs, ordering constraints, why the obvious approach fails
- Workarounds, with a link to the upstream issue
- Performance, security, legal, or compliance constraints
- Links to specs, RFCs, tickets
- Regex intent, and the shape of data it matches
- Doc comments the repo's lint rules or public API conventions require
- License headers
REFACTOR INSTEAD — the comment is a symptom; fix the cause and the comment goes away:
- Explains what a block does → extract a named function
- Labels a magic value → named constant
- Clarifies a vague identifier → rename the identifier
- Explains a condition → guard clause, or a well-named boolean
- Explains what a chunk of a long function does → split the function
Phase 2 — Apply
Deletions first, then refactors. Prefer the smallest refactor that removes the need for the comment — a rename beats an extraction, an extraction beats a restructure. Stay inside the code this branch introduced.
Phase 3 — Verify
- Run the repo's real commands — discover them from
package.jsonscripts,Makefile,justfile, or CI config. Don't assumenpm test. Typecheck, lint, tests, build. - Scope check: the same two commands must match the list recorded in Phase 0. A new file appearing means you edited out of scope — revert it (delete it if untracked).
- Re-read the diff and confirm no logic line changed meaning.
Fix any failure and rerun the checks before reporting. If a failure can't be fixed, revert the edit that caused it and list it under "Needs your call".
Report
## Comment cleanup — <branch>
| File:line | Comment | Action | Reason |
|-----------|---------|--------|--------|
| src/x.ts:42 | `// loop over users` | removed | restates the code |
| src/y.ts:10 | `// 3 retries — payment gateway SLA` | kept | business constraint |
| src/z.ts:88 | `// calculate the discount` | refactored | extracted `calculateDiscount()` |
### Renames & extractions
- `d` → `discountRate` (src/z.ts, 4 references updated)
### Verification
- typecheck / lint / tests: <actual commands and results>
- scope: N files touched, same set as before cleanup
### Needs your call
- <unticketed TODOs, exported-API renames, comments that may encode tribal knowledge>
### Out of scope (not touched)
- <pre-existing issues worth a follow-up>
Notes & edge cases
- Unticketed TODO/FIXME: never delete silently. List it under "Needs your call" — it may be a real open thread.
- Tests: descriptive comments in tests are often redundant with the
it(...)name — fold the meaning into the test name rather than keeping both. - Generated files (lockfiles, codegen output, migrations from a tool): skip entirely, even when they appear in the diff.
- A comment you don't understand is a comment you keep. Flag it instead of deleting — unfamiliarity is not evidence of redundancy.
- Commented-out code: safe to delete; git has it. Say so in the report.