Comment Checker
Agent-written code accumulates narration comments a human never would. This
skill flags every new comment or docstring that is not self-justifying, so the
author must either justify it (complex algorithm, security, regex, public API)
or delete it and make the code clearer instead.
Commands
python3 scripts/comment_checker.py src/foo.py src/bar.ts # scan whole files
git diff | python3 scripts/comment_checker.py --diff # only added lines
git diff main... | python3 scripts/comment_checker.py --diff --fail-over 0 # CI gate
python3 scripts/comment_checker.py --json --diff < changes.patch
What auto-passes (never flagged)
- Shebang lines (
#! on line 1)
- BDD structure comments: given / when / then / arrange / act / assert
- Type-checker and linter directives:
noqa, type:, eslint-disable,
@ts-expect-error, clippy::, nolint, biome-ignore, coverage markers, ...
- Copyright / license headers
- TODO / FIXME / HACK / XXX / NOTE / REVIEW markers
Everything else is reported with file:line and the comment text.
Handling a flag
Priority order, same as the original hook:
- Comment existed before your change - keep, note it is pre-existing.
- Necessary comment - justify it: complex algorithm, security, performance,
regex, math, or public-API docstring.
- Unnecessary - remove it and make the code self-explanatory instead.
Comment-based section dividers (
# ----) mean the file is too long: split it.
Languages
C-family (js/ts/jsx/tsx/java/c/cpp/cs/rust/swift/kotlin/go), hash-family
(python + docstrings, ruby, shell, yaml, toml), html/xml, sql, lua.
1---2name: comment-checker3description: Flags newly written comments and docstrings in files or diffs so an agent must justify or remove them — BDD markers, lint/type directives, license headers, shebangs, and TODO/FIXME markers auto-pass. A standalone CLI port of oh-my-opencode's comment-checker hook, usable by any agent or CI without the OMO harness.4license: MIT (detection rules adapted from oh-my-opencode / oh-my-claudec5---67# Comment Checker89Agent-written code accumulates narration comments a human never would. This10skill flags every new comment or docstring that is not self-justifying, so the11author must either justify it (complex algorithm, security, regex, public API)12or delete it and make the code clearer instead.1314## Commands1516```bash17python3 scripts/comment_checker.py src/foo.py src/bar.ts # scan whole files18git diff | python3 scripts/comment_checker.py --diff # only added lines19git diff main... | python3 scripts/comment_checker.py --diff --fail-over 0 # CI gate20python3 scripts/comment_checker.py --json --diff < changes.patch21```2223## What auto-passes (never flagged)2425- Shebang lines (`#!` on line 1)26- BDD structure comments: given / when / then / arrange / act / assert27- Type-checker and linter directives: `noqa`, `type:`, `eslint-disable`,28 `@ts-expect-error`, `clippy::`, `nolint`, `biome-ignore`, coverage markers, ...29- Copyright / license headers30- TODO / FIXME / HACK / XXX / NOTE / REVIEW markers3132Everything else is reported with file:line and the comment text.3334## Handling a flag3536Priority order, same as the original hook:37381. Comment existed before your change - keep, note it is pre-existing.392. Necessary comment - justify it: complex algorithm, security, performance,40 regex, math, or public-API docstring.413. Unnecessary - remove it and make the code self-explanatory instead.42 Comment-based section dividers (`# ----`) mean the file is too long: split it.4344## Languages4546C-family (js/ts/jsx/tsx/java/c/cpp/cs/rust/swift/kotlin/go), hash-family47(python + docstrings, ruby, shell, yaml, toml), html/xml, sql, lua.
trac3r00