🇺🇸English
Paths: 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. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.
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/audit_worker_core_contract.md.
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_stack for detection) Hex-line acceleration: Use outline(path) to understand code structure (functions, classes) before analyzing comments — identifies which code sections to scan.
- 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.md in 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_worker_core_contract.md and shared/references/audit_scoring.md.
Output Format
MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/templates/audit_worker_report_template.md.
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 |
Critical Rules
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
- 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:line for programmatic navigation
Definition of Done
MANDATORY READ: Load shared/references/audit_worker_core_contract.md.
- 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
- Comment rules and patterns: references/comments_rules.md
Version: 4.0.0 Last Updated: 2026-03-01
Weekly Installs
100
Repository
levnikolaevich/…e-skills
GitHub Stars
253
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
cursor93
claude-code91
codex91
opencode90
github-copilot90
amp90
