Comment Quality

Comment Quality Skill

Review code comments for temporal references, development-activity language, and relative comparisons. Produces structured reports with actionable rewrites that explain WHAT the code does and WHY, only WHAT the code does and WHY. Supports .go, .py, .js, .ts, .md, and .txt files.

Instructions

Phase 1: SCAN

Goal: Identify all comments containing temporal, activity, or relative language.

Step 1: Determine scope

Read the repository CLAUDE.md first to pick up any project-specific comment conventions.

Scan only what was requested. If user specifies files, scan those files. If user specifies a directory, scan that directory. Honor the explicit scope -- even if you suspect other files have issues, honor the explicit scope and suggest expansion separately at the end.

If user explicitly requests auto-fix, enable it. Otherwise present findings for review. For large codebases, group findings by directory when reporting.

Step 2: Search for temporal patterns

Flag every instance of the following categories. No temporal word is "harmless" -- all temporal language ages poorly and must be rewritten regardless of how innocuous it seems:

• Temporal words: "new", "old", "previous", "current", "now", "recently", "latest", "modern"
• Development activity: "added", "removed", "deleted", "updated", "changed", "modified", "fixed", "improved", "enhanced", "refactored", "optimized"
• State transitions: "replaced", "migrated", "upgraded", "deprecated", "became", "turned into", "evolved"
• Date references: "as of", "since", "from", "after", "before"
• Relative comparisons: "better than", "faster than", "instead of", "unlike the previous"

Step 3: Filter false positives

Exclude from findings -- these are not developer comments and must remain untouched:

• Copyright and license headers (legal requirements, not code comments)
• @generated markers (tooling markers)
• @deprecated annotations (keep the tag, flag only temporal explanation text after it)
• Variable names or string literals that happen to contain temporal words
• TODO/FIXME items that describe future work without temporal references

When a finding appears, inspect nearby comments in the same function or block -- temporal language tends to cluster.

Gate: All files in scope scanned. Findings list populated with file path, line number, and matched text. Every finding listed, not just the first few. Proceed only when gate passes.

Phase 2: ANALYZE

Goal: Understand context for each finding to produce meaningful rewrites.

Step 1: Read surrounding code

For each finding, read the function, block, or section the comment describes. Understand what the code actually does. A rewrite without code context produces vague replacements that strip temporal words without adding substance.

Step 2: Classify the comment

| Finding | Type | Severity |
|---------|------|----------|
| "now uses JWT" | Temporal + Activity | High |
| "improved perf" | Activity | Medium |
| "Copyright 2024" | Legal (skip) | N/A |

Step 3: Determine replacement content

For each comment, identify:

1. What does the code do right now?
2. Why does it do it this way?
3. What value does the comment add for a future reader?

Gate: Every finding classified with context understood. Proceed only when gate passes.

Phase 3: REWRITE

Goal: Generate specific, valuable replacement comments.

Step 1: Draft rewrites

For each finding, produce a structured entry with file path, line number, current text, suggested replacement, and reasoning:

**File: `path/to/file.ext`**

Line X - [Comment type]:
  Current:   // Authentication now uses JWT tokens
  Suggested: // Authenticates requests using signed JWT tokens
  Reason:    "now uses" is temporal - describe current behavior only

Step 2: Validate rewrite quality

Each rewrite MUST pass these checks:

• Would this comment make sense in 10 years?
• Does it explain WHAT or WHY, not WHEN?
• Is it more specific than what it replaces (not just temporal word removed)?
• Does it add value for a future maintainer?

If a rewrite just removes the temporal word without adding substance, it fails validation. Simply deleting a word produces a useless comment -- // Updated error handling becoming // Error handling adds nothing. Rewrite with specific, descriptive content: // Handles database connection errors with exponential backoff retry.

Gate: All rewrites pass quality checks. No vague or empty replacements. Proceed only when gate passes.