# Comment Review

> 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.

- Skill: `openkursar/comment-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openkursar/comment-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openkursar/comment-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: openkursar (https://skillmd.com/u/openkursar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openkursar/comment-review

---


# 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.