Comment Review & Improvement Skill
Reviews the comments in the current changes against this project's comment policy
(CLAUDE.md), reports violations, and — after confirmation — fixes them.
The governing principle (from CLAUDE.md): comments transfer context the reader
cannot get from the code itself. Default to none. Keep each comment as short as the
context allows. If removing the comment loses no context, it shouldn't exist.
Workflow
1. Collect the changed comments
- Run
git status and git diff to see uncommitted changes (or the range the user
names, e.g. a branch/commit).
- Focus only on comment lines that were added or modified. Ignore pure logic
diffs and generated files (locale JSON, lockfiles, snapshots).
- For large diffs, save the diff to a file and extract added comment lines, then read
the surrounding code so each comment is judged in context — never judge a comment by
its text alone.
2. Evaluate each comment
Read the code the comment sits on, then decide: keep / trim / delete / rewrite.
Keep (only if the code alone cannot convey it):
- Why a non-obvious decision was made.
- An invariant that must hold, or a trap not visible locally.
- A security/trust boundary, a race-condition hazard, a non-destructive contract.
- A link to an issue/RFC.
Flag for fix — these are violations of the policy:
| # |
Violation |
Example |
Action |
| 1 |
Ceremonial / subjective wording |
"The proud part of the design…", "elegant", "cleanly" |
delete the editorializing |
| 2 |
Planning labels / session IDs |
E1, F2, Phase X, Full-chain:, Helper: |
delete |
| 3 |
Cross-function line references |
"see api.apiKey above", "(see line 120)" |
delete the pointer; state the rule once |
| 4 |
Narrating removed/changed code |
"new — replaces…", "legacy; was…", "the previous branch is gone" |
state the present rule only |
| 5 |
Paraphrasing adjacent code |
// user re-entered — keep it above if (val) return |
delete |
| 6 |
Restating a condition |
// oldest first is borderline; long restatements are not |
trim or delete |
| 7 |
Defensive notes aimed at reviewers |
"Note: this is safe because…" addressed to a PR reader |
delete or reframe as an invariant |
| 8 |
Numbered cross-refs to a scheme defined elsewhere |
"(invariant ②)" |
name the property inline instead |
| 9 |
Over-long blocks |
multi-paragraph essays / worked examples where 2–3 lines suffice |
halve it; keep the one-line why |
Also check the basics from the commit policy:
- Comments in English (open-source convention).
- No internal/private info, no company/brand names.
3. Report before changing anything
Produce a concise report:
- A density signal for the worst files (comment-lines / total-lines) to show over-documentation.
- A prioritized list: clear violations (#1–#5) first, then long-block trims.
- For each item:
file:line, the rule it breaks, and the proposed shorter version.
- Explicitly list what you will keep so valuable rationale is not stripped.
Do not delete-all. Stripping a security/why comment is worse than an over-long one.
4. Fix on confirmation
- Per
CLAUDE.md, code/comment edits require human consent. Wait for the user to
approve (or to pick a subset) before editing.
- Make comment-only edits — never alter logic. Prefer
Edit on the exact block.
- After editing, do a quick pass to confirm no
{@link}/name references now dangle and
no logic line was touched.
Notes
- If there are no comment changes, say so — nothing to review.
- Do not run
git commit or git push; this skill only reviews and edits comments.
- Read
CLAUDE.md (and halo-dev) first if not already in context — it is the source
of truth for the rules above.
- When unsure whether a comment carries real non-local context, keep it and flag it as
"keep (verify)" rather than deleting.
1---2name: comment-review3description: Must be invoked when the user asks to review, audit, or improve code comments — e.g. "check the comment quality", "审一下注释", "注释评审", "optimize the comments". Reviews comments in the current changes against this project's comment policy and fixes the issues found.4---56# Comment Review & Improvement Skill78Reviews the comments in the current changes against this project's comment policy9(`CLAUDE.md`), reports violations, and — after confirmation — fixes them.1011The governing principle (from `CLAUDE.md`): **comments transfer context the reader12cannot get from the code itself. Default to none. Keep each comment as short as the13context allows. If removing the comment loses no context, it shouldn't exist.**1415## Workflow1617### 1. Collect the changed comments1819- Run `git status` and `git diff` to see uncommitted changes (or the range the user20 names, e.g. a branch/commit).21- Focus only on comment lines that were **added or modified**. Ignore pure logic22 diffs and generated files (locale JSON, lockfiles, snapshots).23- For large diffs, save the diff to a file and extract added comment lines, then read24 the surrounding code so each comment is judged in context — never judge a comment by25 its text alone.2627### 2. Evaluate each comment2829Read the code the comment sits on, then decide: **keep / trim / delete / rewrite.**3031**Keep** (only if the code alone cannot convey it):32- *Why* a non-obvious decision was made.33- An invariant that must hold, or a trap not visible locally.34- A security/trust boundary, a race-condition hazard, a non-destructive contract.35- A link to an issue/RFC.3637**Flag for fix** — these are violations of the policy:3839| # | Violation | Example | Action |40|---|-----------|---------|--------|41| 1 | Ceremonial / subjective wording | "The proud part of the design…", "elegant", "cleanly" | delete the editorializing |42| 2 | Planning labels / session IDs | `E1`, `F2`, `Phase X`, `Full-chain:`, `Helper:` | delete |43| 3 | Cross-function line references | "see api.apiKey above", "(see line 120)" | delete the pointer; state the rule once |44| 4 | Narrating removed/changed code | "new — replaces…", "legacy; was…", "the previous branch is gone" | state the present rule only |45| 5 | Paraphrasing adjacent code | `// user re-entered — keep it` above `if (val) return` | delete |46| 6 | Restating a condition | `// oldest first` is borderline; long restatements are not | trim or delete |47| 7 | Defensive notes aimed at reviewers | "Note: this is safe because…" addressed to a PR reader | delete or reframe as an invariant |48| 8 | Numbered cross-refs to a scheme defined elsewhere | "(invariant ②)" | name the property inline instead |49| 9 | Over-long blocks | multi-paragraph essays / worked examples where 2–3 lines suffice | halve it; keep the one-line *why* |5051Also check the basics from the commit policy:52- Comments in **English** (open-source convention).53- No internal/private info, no company/brand names.5455### 3. Report before changing anything5657Produce a concise report:58- A density signal for the worst files (comment-lines / total-lines) to show over-documentation.59- A prioritized list: clear violations (#1–#5) first, then long-block trims.60- For each item: `file:line`, the rule it breaks, and the proposed shorter version.61- Explicitly list what you will **keep** so valuable rationale is not stripped.6263**Do not delete-all.** Stripping a security/why comment is worse than an over-long one.6465### 4. Fix on confirmation6667- Per `CLAUDE.md`, code/comment edits require human consent. Wait for the user to68 approve (or to pick a subset) before editing.69- Make **comment-only** edits — never alter logic. Prefer `Edit` on the exact block.70- After editing, do a quick pass to confirm no `{@link}`/name references now dangle and71 no logic line was touched.7273## Notes7475- If there are no comment changes, say so — nothing to review.76- Do not run `git commit` or `git push`; this skill only reviews and edits comments.77- Read `CLAUDE.md` (and `halo-dev`) first if not already in context — it is the source78 of truth for the rules above.79- When unsure whether a comment carries real non-local context, keep it and flag it as80 "keep (verify)" rather than deleting.
openkursar