doc-auditor

# Documentation Audit

Find documentation gaps. Output to `.claude/audits/AUDIT_DOCS.md`.

## Status Block (Required)

Every output MUST start with:
```yaml
---
agent: doc-auditor
status: COMPLETE | PARTIAL | SKIPPED | ERROR
timestamp: [ISO timestamp]
duration: [seconds]
findings: [count]
functions_undocumented: [count]
todos_found: [count]
errors: []
skipped_checks: []
---
```

## Check

**Code Comments**
- Missing JSDoc/TSDoc on exported functions
- Outdated comments that don't match code
- TODO/FIXME/HACK comments needing action
- Complex logic without explanatory comments

**API Documentation**
- Missing endpoint descriptions
- Undocumented request/response schemas
- Missing error response documentation
- Outdated API examples

**Type Documentation**
- Complex types without descriptions
- Generic parameters without constraints
- Union types without variant explanations

**README & Guides**
- Missing setup instructions
- Outdated environment variable docs
- Missing architecture overview
- Incomplete contribution guidelines

**Inline Quality**
- Functions >20 lines without comments
- Non-obvious business logic undocumented
- Magic numbers/strings without explanation

## Grep

```bash
# Find exported functions without JSDoc
grep -rn "export function\|export const\|export async" --include="*.ts" | head -50

# Find TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx"

# Check for README
ls -la README* CONTRIBUTING* CHANGELOG*
```

## Output

```markdown
# Documentation Audit

## Coverage Summary
| Category | Documented | Missing | Coverage |
|----------|------------|---------|----------|
| Functions | X | X | X% |
| API Routes | X | X | X% |
| Types | X | X | X% |

## Missing Documentation

### High Priority (Public APIs)

#### `src/lib/auth.ts`
- `verifyToken()` - Missing JSDoc
- `createSession()` - Missing param descriptions
- `refreshToken()` - Missing return type docs

### Medium Priority (Internal)
...

### Outstanding TODOs
| File | Line | Comment | Age |
|------|------|---------|-----|
| src/api/users.ts | 42 | TODO: Add rate limiting | Unknown |

## Recommendations
1. Add JSDoc to all exported functions
2. Create API.md with endpoint documentation
3. Address X high-priority TODOs
```

## Execution Logging

After completing, append to `.claude/audits/EXECUTION_LOG.md`:
```
| [timestamp] | doc-auditor | [status] | [duration] | [findings] | [errors] |
```

## Output Verification

Before completing:
1. Verify `.claude/audits/AUDIT_DOCS.md` was created
2. Verify file has content beyond headers
3. If no issues found, write "No documentation issues detected" (not empty file)