Comment Quality Skill
Operator Context
This skill operates as an operator for documentation quality assurance, configuring Claude's behavior for timeless, meaningful code comments and documentation. It implements a Scan, Analyze, Rewrite, Verify workflow with deterministic pattern matching against known temporal and activity language.
Hardcoded Behaviors (Always Apply)
- CLAUDE.md Compliance: Read and follow repository CLAUDE.md before scanning
- Over-Engineering Prevention: Scan only files explicitly requested or in the current working scope. Do NOT scan entire codebases unless user asks for full audit
- Remove ALL Temporal Language: Words like "new", "old", "now", "recently", "updated", "fixed" are NEVER acceptable in comments
- Focus on WHAT and WHY: Comments MUST explain current functionality and purpose, never history or development activity
- No Exceptions for Temporal Language: Every instance is flagged regardless of perceived harmlessness
- Preserve Legal and Generated Markers: Copyright headers, license text, @generated tags, and @deprecated annotations are left unchanged
Default Behaviors (ON unless disabled)
- Concise Reporting: Report facts with file paths and line numbers. No excessive commentary
- Suggest Rewrites: Provide corrected versions of every problematic comment
- Explain Reasoning: Clarify why temporal language fails for long-term maintainability
- Check Surrounding Context: Inspect nearby comments for temporal patterns when one is found
- Report All Findings: List every instance, not just the first few
- Temporary File Cleanup: Remove scan results, intermediate reports, or helper files at task completion
Optional Behaviors (OFF unless enabled)
- Auto-Fix Mode: Automatically apply corrections without user review (enable with explicit request)
- Aggressive Scanning: Check git commit messages and PR descriptions (enable with explicit request)
- Batch Processing: Process files by directory with grouped reports (enable for large codebases)
What This Skill CAN Do
- Identify temporal language, development-activity words, and relative comparisons in comments
- Provide specific, actionable rewrites that explain WHAT and WHY
- Scan multiple file types: , , , , ,
- Distinguish between developer comments and legal/generated markers
- Generate structured reports with file path, line number, current text, and suggested fix
What This Skill CANNOT Do
- Write new documentation from scratch (use documentation skills instead)
- Enforce code style rules beyond comment content (use code-linting instead)
- Fix comments without reading surrounding code context
- Auto-fix without explicit user authorization
- Modify copyright headers, license text, or generated code markers
Instructions
Phase 1: SCAN
Goal: Identify all comments containing temporal, activity, or relative language.
Step 1: Determine scope
Scan only what was requested. If user specifies files, scan those files. If user specifies a directory, scan that directory. NEVER default to full codebase.
Step 2: Search for temporal patterns
Target these categories:
- 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:
- Copyright and license headers
- markers
- annotations (keep the tag, flag only temporal explanation text)
- Variable names or string literals that happen to contain temporal words
- TODO/FIXME items that describe future work without temporal references
Gate: All files in scope scanned. Findings list populated with file path, line number, and matched text. 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.
Step 2: Classify the comment
markdown
|---------|------|----------|
| "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:
- What does the code do right now?
- Why does it do it this way?
- 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:
markdown
**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:
If a rewrite just removes the temporal word without adding substance, it fails validation. Rewrite again with specific, descriptive content.
Gate: All rewrites pass quality checks. No vague or empty replacements. Proceed only when gate passes.
Phase 4: REPORT
Goal: Deliver structured, actionable report.
Step 1: Generate report
markdown
## Comment Quality Review
### Summary
- Files scanned: N
- Issues found: M
- Most common pattern: [temporal word]
### Findings
[All findings with file, line, current text, suggested text, reason]
### Recommendations
1. Apply suggested changes
2. Consider adding linter rules for temporal language prevention
Step 2: Apply fixes (if auto-fix enabled)
If user requested auto-fix, apply all rewrites using Edit tool. Verify each edit succeeded.
Gate: Report delivered. All findings accounted for. Task complete.
Examples
Example 1: Single File Review
User says: "Check the comments in auth.go"
Actions:
- Scan only auth.go for temporal patterns (SCAN)
- Read surrounding code for each finding, classify severity (ANALYZE)
- Draft specific rewrites with WHAT/WHY focus (REWRITE)
- Deliver report with file path, line, current, suggested, reason (REPORT)
Result: Targeted report for one file with actionable rewrites
Example 2: Pre-Release Documentation Audit
User says: "Audit all markdown files in docs/ before release"
Actions:
- Scan all .md files in docs/ directory (SCAN)
- Classify findings, skip license headers and generated markers (ANALYZE)
- Generate rewrites, validate each passes the 10-year test (REWRITE)
- Deliver grouped report sorted by file, with summary statistics (REPORT)
Result: Comprehensive audit with every finding addressed
Example 3: Auto-Fix Mode
User says: "Fix all temporal comments in pkg/api/ automatically"
Actions:
- Scan all code files in pkg/api/ (SCAN)
- Analyze context for each finding (ANALYZE)
- Generate and validate rewrites (REWRITE)
- Apply fixes using Edit tool, verify each succeeded, deliver report (REPORT)
Result: All temporal comments replaced in-place with verification
Error Handling
Error: "No Temporal Language Found"
Cause: Files are clean or scope was too narrow
Solution:
- Verify common files were scanned (README, main source files)
- Report clean results -- this is a valid positive outcome
- Suggest expanding scope if user suspects issues exist elsewhere
Error: "Too Many Results to Display"
Cause: Large codebase with widespread temporal language
Solution:
- Prioritize by file importance (README first, then core modules)
- Group findings by pattern type
- Enable batch processing optional behavior
Error: "Comment Meaning Unclear Without History"
Cause: Comment only makes sense with development context that no longer exists
Solution:
- Read surrounding code to infer current purpose
- If purpose is clear from code, suggest removing the comment entirely
- If purpose is unclear, ask user for clarification before rewriting
Anti-Patterns
Anti-Pattern 1: Scanning Entire Codebase Without Scope
What it looks like: User asks "check comments in auth.go" and agent scans all 500 files
Why wrong: Wastes tokens, produces overwhelming reports, ignores user's explicit request
Do instead: Scan only what was requested. Ask before expanding scope.
Anti-Pattern 2: Vague Rewrites That Remove Without Adding
What it looks like:
// Updated error handling
becomes
Why wrong: Removing temporal word without adding substance produces a useless comment
Do instead:
// Handles database connection errors with exponential backoff retry
Anti-Pattern 3: Flagging Legal Text and Generated Markers
What it looks like: Flagging
as temporal language
Why wrong: Copyright years are legal requirements; generated markers serve tooling
Do instead: Skip license headers, @generated markers, and @deprecated tags
Anti-Pattern 4: Reporting Without Actionable Fixes
What it looks like: "Found 47 instances of temporal language" with no suggested rewrites
Why wrong: Diagnostic-only reports create work without providing solutions
Do instead: Every finding includes file path, line number, current text, suggested fix, and reason
References
This skill uses these shared patterns:
- Anti-Rationalization - Prevents shortcut rationalizations
- Verification Checklist - Pre-completion checks
Domain-Specific Anti-Rationalization
| Rationalization | Why It's Wrong | Required Action |
|---|
| "That temporal word is harmless here" | All temporal language ages poorly | Flag and rewrite it |
| "Removing the word is enough" | Removing without adding produces empty comments | Write specific replacement |
| "Legal text has dates too" | Legal text is not a code comment | Skip legal headers, flag code comments |
| "User only asked about one file" | Nearby files may share patterns | Report scope, suggest expansion if warranted |
Reference Files
${CLAUDE_SKILL_DIR}/references/temporal-keywords.txt
${CLAUDE_SKILL_DIR}/references/examples.md
${CLAUDE_SKILL_DIR}/references/anti-patterns.md