code-comment-discipline
/code-comment-discipline
Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
- Author
- skyf0xx ↗
- Repository
- hedgehog ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
Original author description
Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
How it works
- Default: no comment
- When a comment is allowed
- What a comment must never say
- Applying to existing comments
SKILL.md preview
---
name: code-comment-discipline
description: Apply whenever writing or editing source code in any core's build agent (backend-eng, ui-builder, or equivalent). Governs when a comment belongs at all and what it may say. Default is no comment; a comment is only for the non-obvious. Never restates what the code does, never narrates the task, fix, or conversation that produced it.
---
# Code Comment Discipline
Well-named identifiers and clear structure explain what code does. A
comment earns its place only when it explains something the code cannot:
a hidden constraint, a non-obvious invariant, a workaround for a specific
external bug, or behavior that would surprise a reader.
## Default: no comment
Most lines, functions, and blocks need zero comments. Before writing one,
check whether the same clarity is reachable by renaming a variable or
function instead — prefer that over a comment every time.
## When a comment is allowed
Only for the non-obvious:
- A constraint imposed from outside the code (an API's undocumented
limit, a browser quirk, a platform requirement) that isn't visible at
the call site.
- An invariant the code relies on that isn't implied by types or names
(e.g. "callers must hold the lock before this runs").
- A deliberate workaround for a specific bug in a dependency, with enough
detail to know when it's safe to remove.
- Behavior that looks like a mistake but is intentional.
## What a comment must never say
- What the code does — that's the identifier's job, not the comment's.
- Why *this* task needed the change, who asked for it, or which ticket,
issue, or conversation prompted it.
- History: "used to be X," "changed from Y," "removed Z," "previously,"
"now we," or any other before/after narration. A comment states the
current state and its non-obvious reason only, never how it got there.
- A restatement of the function/variable name in prose ("increments the
counter" above `counter++`).
## Applying to existing comments
When editing a file that already has comments violating these rules,
remove or rewrite them as part of the same change rather than leaving
them in place — don't let a nearby edit normalize the pattern.
Versions
The database has no other skills named code-comment-discipline.
Database snapshot: 13.11.2026 · package version 5b9af566c48d (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 84document-code
Decide whether a comment belongs, and write the ones that do — in Ruby, YAML, a Dockerfile, a shell script, tests or config. Use it before adding any comment, docstring or YARD block, including one you are about to write mid-implementation, and before deleting or rewording one… - 100lean-comments
Audits, writes, and refines maintained first-party source-code comments and declaration-level documentation across languages. Use when adding, editing, reviewing, cleaning up, or auditing comments, doc comments, docstrings, TODO, FIXME, NOTE, suppressions, or other source… - 100pr-comment-reply
Render the canonical reply text for a PR review comment. Use when drafting, writing, or posting a "PR comment reply", "review comment reply", "reply to this comment", "respond to this review comment", "answer the reviewer", "reply on the PR thread", or any text bound for `gh… - 100appropriate-comments-code
Use when writing, editing, or reviewing code in any language and about to add, change, or review a comment, docstring, doc comment, or TODO — especially one that narrates history or a past attempt, restates the line below, explains a feature rather than the code, tells a future… - 85code-comments
What a comment should say, when one is required, when to delete it, and how to handle stale ones. Use when writing or changing code or config files, or when cleaning up legacy comments. Does not cover lint rules, formatting or commit messages. - 100pr-comment-review
This skill should be used when the user asks to review a GitHub pull request AND post the findings as a comment on the PR ('review and comment on PR', 'review PR roi comment len do'). Multi-agent confidence scoring, threshold 80/100, posts via gh. For local working-tree review…