---
name: comment-checker
description: "Comment hygiene workflow adapted for LazyClaude: keep comments useful, remove stale narration, and preserve intent-bearing notes."
---

# Comment Checker

Use this skill after code edits or documentation rewrites where comments may
become stale. The goal is not fewer comments; it is comments that carry intent
the code or tests cannot express.

## Keep Comments That Explain

Keep comments when they explain:

- why a compatibility path exists
- why a safety boundary is conservative
- why a file is generated or packaged
- why a fallback exists for a specific runtime behavior
- why a test asserts a policy rather than exact prose

## Remove Comments That Narrate

Remove or rewrite comments that merely repeat code:

- "read the file"
- "set the variable"
- "loop through items"
- "return result"

If the comment is only true because the current implementation happens to work
that way, prefer a clearer name or a test.

## LazyClaude-Specific Checks

- Comments about Claude registry writes must match actual paths.
- Comments about `/goal` must not imply the plugin can type it silently.
- Comments about `--dry-run` must distinguish inspection from final proof.
- Comments about package contents must match `package.json.files`.
- Comments in tests should explain policy assertions, not every regex.

## Review Flow

1. Search changed files for comments.
2. For each comment, ask whether the next maintainer would be worse off without
   it.
3. Delete narration.
4. Update stale intent comments.
5. Run tests touching the changed files.

## Evidence

For code comments, evidence is the diff plus tests. For docs comments or
markdown policy notes, evidence is docs tests and one manual scan of the
rendered or packaged surface when relevant.
