# Reviewing Comments

> Defines fresh-context source-comment review and findings. Load when auditing comments for removal or enforceable constraint encoding.

- Skill: `bostonaholic/reviewing-comments` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bostonaholic/reviewing-comments`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bostonaholic/reviewing-comments/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bostonaholic (https://skillmd.com/u/bostonaholic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bostonaholic/reviewing-comments

---


# Reviewing Comments

Judge comments independently. Report findings; never edit the files under
review. The invoking producer owns every accepted change.

## Review brief

Review every source comment and suppression directive in the supplied scope.
Use no author conversation or proposed verdict. Tools: Read, Grep, Glob. Do not
run commands that change files, the index, refs, processes, or external state.

Call the Skill tool with `engineering-standards`. Its `## Code Comments`
section is the authority; do not replace it with a new comment style guide.

Treat generated-file markers, required license headers, shebangs, and compiler
or tool directives with semantic effect as syntax, not ordinary comments.
Report skipped generated, vendored, minified, or unreadable files.

Classify each ordinary comment:

- `REMOVE` when it explains what code does, duplicates another contract,
  narrates process, cites internal work tracking, leaves dead code, carries a
  TODO/FIXME, is obsolete, or cannot be verified. Mark it `comment-only` when
  deletion is sufficient; otherwise mark it `root-cause` and name the smallest
  correction needed before deletion.
- `KEEP` only for a current, non-obvious why or public-interface contract whose
  fact cannot be expressed by naming, types, runtime checks, tests, lint, or CI.
  Cite evidence for the constraint and for why mechanical encoding is not
  available in scope.
- `ENCODE` when a comment asserts an enforceable rule we control, including
  “do not remove,” fixed wording, required consultation, or a lint/type/coverage
  suppression. Name the cheapest `type`, `runtime`, `test`, `lint`, or `CI`
  enforcement. Correctness and security suppressions never qualify as `KEEP`.

Ambiguity is not evidence for deletion. Classify it `KEEP` and state what could
resolve it. Do not flag an intentional comment merely because it survived the
decision test.

## Report format

List findings in file order using exactly one form per comment:

```text
- REMOVE <file>:<line> [comment-only|root-cause] — <failed rule and evidence>
- KEEP <file>:<line> — <constraint and evidence>
- ENCODE <file>:<line> [type|runtime|test|lint|CI] — <constraint and encoding>
```

Then report counts for reviewed comments, `REMOVE`, `KEEP`, `ENCODE`, and
skipped files. End with exactly one verdict line:

- `APPROVE` — no `REMOVE` or `ENCODE` findings.
- `REQUEST CHANGES` — at least one `REMOVE` or `ENCODE` finding.