Docs Check — Documentation Coverage Enforcement

Scope boundary: docs-check covers missing and misleading prose documentation. It does not flag commented-out code — that is dead-check's domain (DEAD-1). Do not raise DOCS violations for code that has been commented out; raise DEAD-1 instead.

Precedence in the overall system: SEC → TDD → ARCH/TYPE → DOCS-1 through DOCS-3 (all WARN).

---

Rules

DOCS-1 — Missing JSDoc / Docstring on Exported Symbol

Severity: WARN | Languages: typescript, javascript, python, go | Source: CCC

What it prohibits: Exported functions, classes, interfaces, and public methods with no documentation comment. Callers cannot understand the contract without docs.

Prohibited patterns:

// TypeScript/JavaScript
export function foo(...) { }        // no preceding /** ... */ JSDoc block
export class Foo { }                // no JSDoc

# Python
def public_function(...):           # no docstring (first statement not a string literal)
class PublicClass:                   # no docstring

// Go
func ExportedFunction(...) { }      // no preceding // ExportedFunction ... comment
type ExportedType struct { }        // no preceding // ExportedType ... comment

Exemptions:

• Private/unexported symbols (prefixed with _ in Python/JS, lowercase in Go)
• Simple getters/setters whose name is fully self-documenting and have no parameters
• Test files

Detection:

1. Grep for export function, export class, export const.*=.*function, export const.*=> with no preceding comment block
2. Grep for ^def [^_] or ^class [^_] in Python (matches any top-level public function or class — names starting with _ are private) with no """ or ''' docstring on the next line; also honour __all__ when present
3. Grep for ^func [A-Z] in Go with no preceding // comment line
4. For each match: verify the symbol is not in a test file and is not private/unexported

agent_action:

1. Cite: DOCS-1 (WARN): Exported symbol '{name}' at {file}:{line} has no documentation comment.
2. Show the undocumented symbol
3. Propose a minimal JSDoc/docstring template:

   /**
    * Brief description of what {name} does.
    *
    * @param paramName - description
    * @returns description
    */
   

4. If --fix: insert the template above the symbol — require human to fill in the description

---

DOCS-2 — Misleading or Stale Inline Comment

Severity: WARN | Languages: typescript, javascript, python, go | Source: CCC

What it prohibits: Inline comments that contradict the code they annotate. Signs of staleness: comments referencing removed variables, old function names, or superseded logic. Comments that reference code which no longer exists nearby indicate structural staleness.

Prohibited patterns:

// TypeScript/JavaScript
// calls foo()
bar();                              // comment says foo, code says bar

# Python
# returns the user ID
def get_users() -> list[User]:      // comment says ID, function returns list

// Go
// deprecated, use NewParser instead
func Parse() { }                    // NewParser does not exist in this file

Exemptions:

• TODOs and FIXMEs (tracked separately)
• License/copyright headers
• Auto-generated comments (e.g., // Code generated by ...)

Detection:

1. For each inline comment: check if it references a symbol name (function, variable, type) that does not appear within 5 lines of the comment
2. Look for comment-to-code mismatches: comment says "calls X" but code calls Y; comment says "returns X" but signature returns Y
3. This is a best-effort pattern match, not a semantic analysis — flag only high-confidence mismatches

agent_action:

1. Cite: DOCS-2 (WARN): Stale comment at {file}:{line} — references '{symbol}' which no longer exists nearby.
2. Show the comment and the contradicting code
3. Ask developer to update or remove the comment
4. If --fix: remove the stale comment and add a // TODO: add accurate comment placeholder — do not attempt to auto-generate a corrected comment

---

DOCS-3 — Missing README in New Package / Module Directory

Severity: WARN | Languages: typescript, javascript, python, go | Source: CCC

What it prohibits: New directories that contain source files but no README.md. Applies to directories that appear to be a new module/package (contain index.ts, __init__.py, package.json, or a Go package declaration) but have no README.md alongside them.

Prohibited patterns:

src/payments/
  ├── index.ts
  └── (no README.md)

pkg/auth/
  ├── auth.go
  └── (no README.md)

src/utils/database/
  ├── __init__.py
  └── (no README.md)

Exemptions:

• Top-level project root (README.md is expected to exist already)
• Test directories (__tests__/, *_test.go directories)
• Config-only directories (no source files, only YAML/JSON/env files)
• Very small utility files (< 2 exported symbols) where inline docs suffice

Detection:

1. For each new directory in the diff: check if it contains source files (.ts, .js, .py, .go) and an entry point (index.ts, __init__.py, package.json, or Go package declaration)
2. Check if README.md exists in that directory
3. If source files are present and no README.md: flag as DOCS-3

agent_action:

1. Cite: DOCS-3 (WARN): Directory '{path}' contains source files but no README.md.
2. Show the directory path and its source files
3. Propose creating a minimal README.md with:
   • Module name (derived from directory name)
   • One-sentence description
   • Key exports
   • Usage example
4. If --fix: create the README.md stub — require human to fill in the description and usage example

---

Report schema: see skills/conductor/shared-contracts.md.