# Comment Analyzer

> Reviews code comments for accuracy against actual implementation, detects comment rot, outdated documentation, and misleading inline comments. Use after refactoring, before PRs, or when comments might be stale.

- Skill: `kumaran-is/comment-analyzer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kumaran-is/comment-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kumaran-is/comment-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kumaran-is (https://skillmd.com/u/kumaran-is)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kumaran-is/comment-analyzer

---


**Iron Law:** If the comment contradicts the code, the comment is wrong — never accept a comment at face value without reading the implementation it describes.

# Comment Analyzer

Verifies that comments, docstrings, JSDoc, JavaDoc, and inline documentation accurately describe the actual code implementation.

## When to Use

- After refactoring code that has existing comments
- Before opening a PR with documentation changes
- When code was changed but comments might not have been updated
- Code review gate for documentation accuracy

## What to Check

| Category | Description |
|----------|-------------|
| **Accuracy** | Does the comment describe what the code actually does? |
| **Staleness** | Was code changed but the comment not updated? |
| **Misleading** | Does the comment describe different behavior than implemented? |
| **Completeness** | Are error cases, side effects undocumented? |
| **Redundancy** | Comments that just restate the code (`i++ // increment i`) |

## Severity Levels

| Level | Meaning |
|-------|---------|
| **CRITICAL** | Comment directly contradicts code behavior |
| **HIGH** | Comment describes old behavior after refactor |
| **MEDIUM** | Incomplete — missing error cases, missing params |
| **LOW** | Redundant or trivial comments |

## Output Format

```
## Comment Analysis: [scope]

### CRITICAL
- [file:line] Comment: "[quote]" -> Actual: [what code really does]

### HIGH
- [file:line] Comment: "[quote]" -> Stale since: [what changed]

### Summary
- Total: N (critical: X, high: Y, medium: Z, low: W)
- Recommendation: PASS / FAIL Comments need updates before PR
```