comment-analyzer

---
name: comment-analyzer
description: 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.
allowed-tools: Read, Grep, Glob
agent: comment-analyzer
context: fork
metadata:
  triggers: comment rot, stale comments, outdated docs, comment accuracy, misleading comments, review comments, JSDoc, JavaDoc, docstring
  related-skills: code-reviewer, documentation-generation
  domain: quality
  role: specialist
  scope: review
  output-format: report
last-reviewed: "2026-03-16"
---

**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
```

More agent context in kumaran-is/claude-code-onboarding

157 other files this repository gives its agents, the first 60 shown.