comment-analyzer

What This Skill Does

The comment-analyzer is a sophisticated OpenClaw AI agent skill designed to act as a tireless documentation watchdog. It performs deep structural and semantic audits on source code comments, moving beyond simple syntax checking to evaluate the 'why' and 'how' of your codebase. It systematically cross-references code logic against its JSDoc or descriptive comments, flagging inaccuracies that could mislead developers, such as outdated parameters, misleading return value descriptions, or abandoned TODO items. By maintaining high-quality documentation, this skill helps prevent 'comment rot' and ensures that technical debt is clearly communicated rather than obscured by ambiguous or incorrect annotations.

Installation

To integrate this agent skill into your workspace, run the following command in your terminal: clawhub install openclaw/skills/skills/anton-abyzov/sw-comment-analyzer

Use Cases

This tool is ideal for:

• Code Reviews: Automatically identifying discrepancies between documentation and implementation before a pull request is merged.
• Legacy Code Maintenance: Auditing aging codebases to identify stale comments, broken documentation links, and deprecated implementation references.
• Onboarding Assistance: Ensuring that complex modules are accurately documented so new developers can understand the business logic and assumptions without having to manually trace every line.
• Documentation Refactoring: Cleaning up 'noisy' comments, such as obvious statements that add no value, allowing the code to speak for itself while preserving necessary context.

Example Prompts

1. "Analyze this file and report any discrepancies between the function signatures and the JSDoc parameters, specifically looking for missing @throws documentation."
2. "Review the comments in this module. Flag any obvious comments that should be removed and identify any stale TODOs that are older than six months."
3. "Check if the comments in this controller accurately reflect the current API side effects and edge case handling logic."

Tips & Limitations

To get the most out of the comment-analyzer, ensure your codebase follows standard documentation practices like JSDoc. While the agent is excellent at identifying logical inconsistencies and missing context, it is not a substitute for comprehensive unit testing. Use it to maintain documentation health, not to validate code runtime safety. Remember that the skill performs better when you provide specific scope; running it on a per-file or per-module basis yields more actionable feedback than scanning entire repositories at once.