comment-guidelines_skill

Overview

This skill enforces concise, high-value code comments across configuration and dotfiles. It removes redundant WHAT comments and adds targeted WHY comments when modifying code to reduce cognitive load and surface important design intent.

How this skill works

Whenever code is edited, the skill inspects nearby comments and the changed code. It deletes comments that merely restate code, preserves and updates comments that explain intent or trade-offs, and inserts brief strategic comments for non-obvious behavior, edge cases, or interface contracts.

When to use it

• Automatically on any commit or edit that changes configuration code (Lua, shell, Nix, etc.)
• When reviewing code to reduce confusing or stale comments
• While adding features that introduce edge cases or trade-offs
• When documenting public functions, plugins, or cross-module interactions
• During refactors to remove redundant commentary

Best practices

• Prefer self-documenting names and structure; add comments only for intent and rationale
• Remove comments that repeat code; update comments when behavior changes
• Explain WHY, not WHAT — focus on decisions, constraints, and gotchas
• Keep comments short, specific, and colocated with the relevant code
• Use comments for interface contracts, edge cases, and cross-module assumptions

Example use cases

• Normalize a user input field and add comment explaining case-insensitive matching requirement
• Refactor a plugin setup and remove redundant line-by-line comments that restate configuration keys
• Add a note explaining a workaround for a Neovim API bug in a specific version
• Document why a loop iterates in reverse to allow safe removal during iteration
• Annotate a public helper function with its expected input shapes and error semantics