| name | comment-discipline |
| description | Use only when explicitly asked to clean up AI-narration/redundant comments in a diff, or to adjudicate comment vs. commit-message vs. test-name content for a specific change. The always-on Why-not comment rule lives in AGENTS.md; this skill is the explicit cleanup/adjudication protocol only. Do not use for C++ Doxygen/public-API docs (`code-readability`), or when no explicit comment decision is in scope. |
| metadata | {"short-description":"Comment channel discipline","visibility":"explicit-only","requires":["references/comment-discipline.md"]} |
Purpose
Use this skill to decide what information belongs in an implementation
comment versus a commit message versus a test name, and to remove
AI-generated comments that restate code instead of adding what code cannot
express.
When to use
Use this skill when at least one trigger applies:
- Writing or reviewing implementation comments in a diff.
- Cleaning up AI-generated or redundant comments (narrated diffs, restated
purposes, section banners, correctness arguments to a reviewer).
- Deciding what content goes in a comment, a commit message, or a test
name/description for the same change.
- Writing a commit message and deciding what to include.
Do not use this skill for:
- C++ Doxygen headers or public-API documentation comments — those are
governed by the
code-readability documentation gate, a different genre
(contract documentation).
- Implementation work with no comment, commit-message, or test-naming
decision in scope.
Boundaries
code-readability owns the C++ Doxygen gate and public-API documentation
comments (contract documentation, i.e. What at the API boundary); those
stay mandatory where that gate applies and are exempt from this skill.comment-discipline owns implementation-comment content, commit-message
content decisions, and test name/description content — not documentation
formatting or test framework mechanics.
How to use
-
Open references/comment-discipline.md. Select the relevant section(s)
and cite them by heading name in your reasoning.
-
For each new or edited implementation comment, ask: is this Why-not
information (constraint, rejected alternative, hazard, external
requirement)? If not, delete it.
-
If a comment restates How (narrates adjacent code) or What (restates the
unit's purpose), delete it. If the urge came from unclear code,
rename/restructure instead — see code-readability §4 Comments.
-
Scan for AI-specific anti-patterns (diff narration, correctness
arguments, section banners, prose type signatures, who/when metadata) and
remove them.
-
For test code, move expected-behavior statements into the test
name/structure; do not restate them in a comment above the assertion.
-
For the commit message, state Why (motivation, constraint, trade-off) in
English; do not narrate the diff file-by-file.
-
Leave public API documentation comments required by the
code-readability gate untouched.
Output expectation
- List each kept comment with the Why-not category it satisfies (constraint
/ rejected alternative / hazard / external requirement).
- List each removed or rewritten comment and whether it was replaced by a
rename/restructure.
- Confirm test names/structure carry the expected behavior instead of
comments.
- Confirm the commit message states Why, not a diff narration, in English.
- State that API-doc comments required by the
code-readability gate were
left untouched.
