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.

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

1. Parse Context: Extract tech stack, project root, output_dir from contextStore
2. Scan: Find all source files (use tech_stack for detection)
3. Extract: Parse inline comments + docstrings/JSDoc
4. Audit: Run 6 category checks (see Audit Categories below)
5. Collect Findings: Record each violation with severity, location (file:line), effort estimate (S/M/L), recommendation
6. Calculate Score: Count violations by severity, calculate compliance score (X/10)
7. 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
8. 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