ln-613-code-comments-auditor
Scannednpx machina-cli add skill levnikolaevich/claude-code-skills/ln-613-code-comments-auditor --openclawPaths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
Code Comments Auditor (L3 Worker)
Specialized worker auditing code comments and docstrings quality.
Purpose & Scope
- Worker in ln-610 coordinator pipeline - invoked by ln-610-docs-auditor
- Audit code comments for quality and compliance across 6 categories
- Universal for any tech stack (auto-detect comment syntax)
- Return structured findings to coordinator with severity, location, recommendations
- Calculate compliance score (X/10) for Code Comments category
Inputs (from Coordinator)
MANDATORY READ: Load shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract for contextStore structure.
Receives contextStore with: tech_stack, project_root, output_dir.
Workflow
- Parse Context: Extract tech stack, project root, output_dir from contextStore
- Scan: Find all source files (use
tech_stackfor detection) - Extract: Parse inline comments + docstrings/JSDoc
- Audit: Run 6 category checks (see Audit Categories below)
- Collect Findings: Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
- Calculate Score: Count violations by severity, calculate compliance score (X/10)
- Write Report: Build full markdown report per
shared/templates/audit_worker_report_template.md, write to{output_dir}/613-code-comments.mdin single Write call - Return Summary: Return minimal summary to coordinator (see Output Format)
Audit Categories
| # | Category | What to Check |
|---|---|---|
| 1 | WHY not WHAT | Comments explain rationale, not obvious code behavior; no restating code |
| 2 | Density (15-20%) | Comment-to-code ratio within range; not over/under-commented |
| 3 | No Forbidden Content | No dates/authors; no historical notes; no code examples in comments |
| 4 | Docstrings Quality | Match function signatures; parameters documented; return types accurate |
| 5 | Actuality | Comments match code behavior; no stale references; examples runnable |
| 6 | Legacy Cleanup | No TODO without context; no commented-out code; no deprecated notes |
Scoring Algorithm
MANDATORY READ: Load shared/references/audit_scoring.md for unified scoring formula.
Output Format
MANDATORY READ: Load shared/templates/audit_worker_report_template.md for file format.
Write report to {output_dir}/613-code-comments.md with category: "Code Comments" and checks: why_not_what, density, forbidden_content, docstrings_quality, actuality, legacy_cleanup.
Return summary to coordinator:
Report written: docs/project/.audit/ln-610/{YYYY-MM-DD}/613-code-comments.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
Severity mapping:
| Issue Type | Severity |
|---|---|
| Author names, dates in comments | CRITICAL |
| Commented-out code blocks | HIGH |
| Stale/outdated comments | HIGH |
| Obvious WHAT comments | MEDIUM |
| Density deviation >5% | MEDIUM |
| Minor density deviation | LOW |
Reference Files
- Comment rules and patterns: references/comments_rules.md
Critical Rules
- Do not auto-fix: Report violations only; coordinator aggregates for user
- Fix code, not rules: NEVER modify rules files (*_rules.md, *_standards.md) to make violations pass
- Code is truth: When comment contradicts code, flag comment for update
- WHY > WHAT: Comments explaining obvious behavior should be removed
- Universal: Works with any language; detect comment syntax automatically
- Location precision: Always include
file:linefor programmatic navigation
Definition of Done
- contextStore parsed successfully (including output_dir)
- All source files scanned (tech stack from contextStore)
- All 6 categories audited
- Findings collected with severity, location, effort, recommendation
- Score calculated using penalty algorithm
- Report written to
{output_dir}/613-code-comments.md(atomic single Write call) - Summary returned to coordinator
Reference Files
- Worker report template:
shared/templates/audit_worker_report_template.md - Audit scoring formula:
shared/references/audit_scoring.md - Audit output schema:
shared/references/audit_output_schema.md - Comment rules and patterns: references/comments_rules.md
Version: 4.0.0 Last Updated: 2026-03-01
Source
git clone https://github.com/levnikolaevich/claude-code-skills/blob/master/ln-613-code-comments-auditor/SKILL.mdView on GitHub Overview
Audits code comments and docstrings for quality and compliance across six categories. It detects WHY-not-WHAT, checks comment density, forbids sensitive content, validates docstrings against signatures, and flags stale or misleading content, returning structured findings and a final score.
How This Skill Works
The worker loads context from contextStore, scans files using the detected tech stack, extracts inline comments and docstrings, performs six category audits (WHY not WHAT, density, forbidden content, docstrings quality, actuality, legacy cleanup), and records severity, location, and recommendations for each finding. It then computes a compliance score, writes a single Markdown report to output_dir named 613-code-comments.md with category Code Comments, and returns a concise summary to the coordinator.
When to Use It
- Before merging changes to ensure WHY-not-WHAT, not just code behavior, is understood across the team.
- When starting a new multi-language project to auto-detect comment syntax and enforce consistent auditing.
- During code reviews to verify comment density sits near 15-20% and avoids obvious WHAT statements.
- For legacy code cleanup to remove stale, deprecated, or commented-out content and to verify docstrings match signatures.
- In CI pipelines to generate a standardized audit report for visibility in release notes.
Quick Start
- Step 1: Provide contextStore with tech_stack, project_root, and output_dir, then run ln-613-code-comments-auditor as part of the workflow.
- Step 2: The worker scans source files, extracts comments/docstrings, and runs all six category checks.
- Step 3: Retrieve {output_dir}/613-code-comments.md and review the Code Comments report and the computed Score.
Best Practices
- Favor WHY-not-WHAT explanations over restating code behavior.
- Maintain a comment density near 15-20% unless project-specific guidelines say otherwise.
- Eliminate forbidden content: no author dates, historical notes, or executable examples in comments.
- Keep docstrings aligned with function signatures, documenting parameters and return types accurately.
- Treat the audit as a quality gate: fix findings before merges; do not auto-fix rules themselves.
Example Use Cases
- Auditing a mixed Python/JS repo to ensure docstrings and inline comments meet the six-category standards.
- Cleaning up a legacy codebase by removing deprecated notes and stale references flagged by the auditor.
- Integrating the tool into a CI pipeline to generate a weekly Code Comments report for a large enterprise project.
- Using universal syntax detection to audit code in a polyglot codebase without language-specific configurations.
- Generating PR-ready findings with severity, location, and actionable recommendations for reviewers.
