# Ln 613 Code Comments Auditor

> Checks inline code documentation quality: WHY-not-WHAT, density, forbidden content, docstrings quality, actuality, legacy cleanup. Use when auditing comments and docstrings.

- **Type:** Skill
- **Install:** `agentstack add skill-levnikolaevich-claude-code-skills-ln-613-code-comments-auditor`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [levnikolaevich](https://agentstack.voostack.com/s/levnikolaevich)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [levnikolaevich](https://github.com/levnikolaevich)
- **Source:** https://github.com/levnikolaevich/claude-code-skills/tree/master/plugins/codebase-audit-suite/skills/ln-613-code-comments-auditor
- **Website:** https://levnikolaevich.github.io/claude-code-skills/

## Install

```sh
agentstack add skill-levnikolaevich-claude-code-skills-ln-613-code-comments-auditor
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Inline Code Documentation Auditor (L3 Worker)

**Type:** L3 Worker

Specialized worker auditing inline code documentation quality: comments, docstrings, and language-specific documentation blocks.

## Purpose & Scope

- Audit inline code documentation 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 Inline Code Documentation category
- Scope is limited to comments/docstrings/JSDoc/XML docs
- Out of scope: code design quality, naming quality, test quality, architecture quality, or feature correctness except where comments contradict code

## Inputs

**MANDATORY READ:** Load `references/audit_worker_core_contract.md` and `references/mcp_tool_preferences.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)
   **Hex-line primary path:** Use `outline(file_path)` and discovery-first `read_file()` for code files before analyzing comments. Use `edit_ready=true, verbosity="full"` only if the audit turns into a follow-up edit. Do not use `hex-graph` here - comment quality is a code-reading problem, not a semantic graph problem.
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 `references/templates/audit_worker_report_template.md`, write to `{output_dir}/ln-613--global.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 unsupported notes |

## Scoring Algorithm

**MANDATORY READ:** Load `references/audit_scoring.md`.

## Output Format

**MANDATORY READ:** Load `references/templates/audit_worker_report_template.md`.

Write JSON summary per `references/audit_summary_contract.md`. In managed mode the caller passes both `runId` and `summaryArtifactPath`; in standalone mode the worker generates its own run-scoped artifact path per shared contract.

Write report to `{output_dir}/ln-613--global.md` with `category: "Inline Code Documentation"` and checks: why_not_what, density, forbidden_content, docstrings_quality, actuality, legacy_cleanup.

Return summary per `references/audit_summary_contract.md`.

When `summaryArtifactPath` is absent, write the standalone runtime summary under `.hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json` and optionally echo the same summary in structured output.
```
Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-613--global.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

Apply the already-loaded `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 the documentation for update; do not turn this into a general code-quality review
- **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

Apply the already-loaded `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}/ln-613--global.md` (atomic single Write call)
- [ ] Summary written per contract

## Reference Files

- Comment rules and patterns: [references/comments_rules.md](references/comments_rules.md)

---
**Version:** 4.0.0
**Last Updated:** 2026-03-01

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [levnikolaevich](https://github.com/levnikolaevich)
- **Source:** [levnikolaevich/claude-code-skills](https://github.com/levnikolaevich/claude-code-skills)
- **License:** MIT
- **Homepage:** https://levnikolaevich.github.io/claude-code-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-levnikolaevich-claude-code-skills-ln-613-code-comments-auditor
- Seller: https://agentstack.voostack.com/s/levnikolaevich
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.