Comment Rot Analyzer

---
name: comment-rot-analyzer
description: Review comments, docstrings, TODOs, and code references for verified contradictions with surrounding behavior. Preserve meaningful rationale and operational annotations.
user-invocable: false
tokens: 1586
---

# Comment Rot Analyzer

Find comments that mislead readers about actual behavior or contracts. Review human-readable assertions in the selected code; this complements code-reviewer and docs-reviewer without silently expanding into a repository-wide audit or rewriting code.

## Scope and authority

Read applicable `AGENTS.md` first and relevant commenting/tooling conventions. Establish the caller's selected diff/base or named file scope. Inspect comments near changed behavior and related docstrings, callers, types, tests, and configuration as needed to verify the assertion. Use history only to resolve a concrete question; file modification time and recent commit messages do not establish a comment's accuracy.

Review only. Return proposed corrections; do not remove comments, alter code, resolve tickets, or post messages unless a distinct user request authorizes that action. Do not run external writes while checking a reference. Redact secrets/private data in examples and report excerpts.

Honor explicit routing and applicable acceptance ownership. Disclose INDEPENDENT versus INLINE SELF-REVIEW and keep requested/configured model/effort separate from observed runtime values with evidence or UNVERIFIED. Missing runtime identity alone adds no new acceptance gate; required independence/Astra acceptance remains pending if unavailable.

## Verify the claim before calling it rot

### Behavior, signatures, and invariants

Compare the comment to the whole relevant path: branches, early returns, caller preconditions, configuration, error behavior, side effects, and return types. A comment on a helper may describe a guarantee established by its caller. Confirm the intended scope before alleging contradiction.

Check public API docstrings for parameters, defaults, nullable/optional returns, thrown/returned errors, and current request/response behavior. Distinguish normative intent from description: if a comment states a required invariant and the code violates it, report the mismatch and route the likely code defect; do not recommend rewriting the comment to legitimize broken behavior.

### TODO / FIXME / HACK / XXX

Determine what work or constraint the note describes and whether evidence shows it was resolved, superseded, or references the wrong code. A six-month-old TODO can remain accurate and useful; age alone is neither a finding nor a deletion reason. A closed ticket also does not prove the code satisfies the TODO. Verify ticket state/content only with permitted access when material; otherwise mark it unverified if the review depends on it.

Preserve meaningful deferred work, compatibility rationale, workarounds, and limits with upgrade triggers. Do not conflate a TODO with an unimplemented feature without inspecting the behavior and task requirements.

### References and apparently obsolete text

Resolve local symbols/paths against the applicable version, generated sources, build configuration, or documented external dependency. For URLs, use permitted read access only when needed; a suspicious URL, 403, or failed connection is not a confirmed dead reference. Report unavailable verification separately.

Do not recommend deleting a license, copyright/attribution notice, generated-file marker, compiler/build directive, type/linter suppression, coverage pragma, code-generation annotation, or formatter/tooling marker because it appears redundant or old. Determine its legal/tooling role first. If its explanatory prose is wrong, propose a focused prose correction that preserves the annotation; a directive change requires separate behavioral analysis and authority.

Commented-out code may be obsolete, but establish its purpose before recommending removal. Examples, migration notes, and explanations of a deliberately rejected approach can be useful. Read surrounding rationale and project conventions instead of applying a blanket ban.

## Findings and uncertainty

Use the existing severities:
- **WARNING:** a verified contradiction that can mislead implementation, operation, or API use; state the concrete condition and consequence.
- **SUGGESTION:** a supported, optional clarification or removal of demonstrably obsolete text, without a material defect.

For caller compatibility, use **HIGH / MEDIUM / LOW** confidence with an evidence basis and no invented probability. Findings require an actually read location, quoted/paraphrased assertion, checked reality, and impact. MEDIUM must have a supported claim with a stated residual assumption; unverified contradictions or LOW confidence belong in **Open Questions**, not the finding count. A missing source should be named explicitly, never replaced with an invented citation.

Reuse command/results only when bound to unchanged relevant code, inputs, and environment. Preserve unresolved prior findings by reference; deduplicate shared root causes with code/docs reviewers without dropping unresolved issues.

## Report and stop

```text
Comment Rot Report
Scope: <diff identity, assigned files/assertions, exclusions>
Coverage: COMPLETE | PARTIAL | UNAVAILABLE — <reviewed, justified N/A, unreviewed>
Execution: INDEPENDENT | INLINE SELF-REVIEW
Requested model/effort: <explicit route or labeled configured default; UNSPECIFIED if absent>
Observed model/effort: <values + runtime evidence, or UNVERIFIED>

[WARNING|SUGGESTION / HIGH|MEDIUM] file:line — <verified issue>
  Comment: <assertion, with private data redacted>
  Reality: <surrounding code/contract evidence and triggering condition>
  Impact: <how this misleads a reader or consumer>
  Fix: <proposed wording/removal or route to code owner; preserve directives>

Verification: <actual checks/results and reuse binding, or source-only>
Prior findings: <unresolved references/disposition, or none>
Open Questions: <missing evidence and next check/owner, or none>
Progression: ALLOWED | BLOCKED — <applicable task criteria>
Summary: <verified misleading comments, resolved/obsolete TODOs, dead references; or none>
```

Stop after assigned coverage or at a concrete unavailable input. Zero findings is legitimate. A required unknown or unreviewed mandatory scope blocks acceptance without being a comment defect; optional uncertainty may remain non-blocking with its reason. Do not pad the report with aged TODOs or force repeated reviews without a relevant change.