tl-docs-audit

<!-- Copyright (c) 2026 Todd Levy. Licensed under MIT. SPDX-License-Identifier: MIT -->

Documentation Audit

Audit existing documentation for gaps, staleness, and sync issues. Generates actionable sync reports.

When to Use

• "audit the docs"
• "review doc coverage"
• "find outdated docs"
• "sync docs with code"
• "docs audit"
• "check documentation gaps"
• Joining a project with existing documentation
• After major refactoring
• Quarterly documentation review

For creating new docs from scratch, see tl-docs-create.

Outcomes

• Decision: Sync report with categorized findings
• Decision: Code-to-docs mapping table
• Decision: Prioritized list of proposed edits
• Artifact (optional): Fixed documentation

---

Configuration Discovery

Before auditing, gather scope through structured questions. See references/​configuration.md for full schemas.

Question Flow Summary

1. Light scan — Inventory existing docs
2. Scope — Full audit / Changed files only / Specific areas
3. Output — Report only / Report + fixes
4. Fix confirmation — Per-finding approval (if fixing)

---

Phase 1: Feature Inventory

Scan the codebase for documentable elements before comparing.

What to Inventory

Inventory Format

## Feature Inventory

### Public API
- `createUser(options)` — Creates a new user
- `getUser(id)` — Retrieves user by ID

### CLI Commands
- `pnpm dev` — Start dev server
- `pnpm build` — Production build

---

Phase 2: Doc-First Pass

Walk through existing docs and check coverage against the feature inventory.

Process

1. List all documentation files
2. For each file, extract topics and features referenced
3. Cross-reference against feature inventory
4. Flag gaps by category

Finding Categories

---

Phase 3: Code-First Pass

Start from code and verify each element has adequate documentation.

Code-to-Docs Mapping

Create a mapping table for ongoing maintenance.

Verification Checklist

For each code element:

• Documented somewhere?
• Documentation accurate to current implementation?
• Examples work with current API?
• Linked from appropriate index/​overview page?

---

Phase 4: Sync Report

Generate a structured report of findings.

Report Template

# Documentation Sync Report

Generated: YYYY-MM-DD
Scope: Full codebase analysis

## Summary

| Category | Count |
|----------|-------|
| Missing | 3 |
| Outdated | 2 |
| Structural | 1 |
| Orphaned | 0 |

## Doc-First Findings

### Missing Content

| Page | Missing | Evidence |
|------|---------|----------|
| `docs/​api/​users.md` | PATCH endpoint | `src/​api/​users.ts:45` exports `updateUser` |

### Outdated Content

| Page | Issue | Correct Info |
|------|-------|--------------|
| `docs/​config.md` | Default port shown as 8080 | Default is 3000 |

## Code-First Gaps

| Feature | Evidence | Suggested Location |
|---------|----------|-------------------|
| `validateEmail` helper | Exported in `src/​utils/​email.ts` | `docs/​reference/​utils.md` |

## Proposed Edits

1. **docs/​api/​users.md** — Add PATCH endpoint documentation
2. **README.md** — Add "Database Setup" section

---

Phase 5: Optional Fixes

If user selected "Report + fixes", implement proposed edits.

Fix Process

1. Present each proposed edit for confirmation
2. Use tl-docs-create writing standards for consistency
3. Add "Last Updated" date to modified files
4. Run verification checklist

---

Lifecycle Integration

Run audits at key moments.

Staleness Indicators

Flag docs as potentially stale if:

• Not updated in 90+ days
• References deprecated APIs
• Links to removed files
• Mentions outdated dependency versions

---

Shared Content Handling

When content appears in multiple places, identify the source of truth.

Principles

1. Edit source, not duplicates — Find the canonical location
2. Use links over repetition — Reference instead of copying
3. Sync, don't diverge — If duplication is necessary, ensure consistency

---

References

Skill References

Automated Tooling

• Vale — Prose linting (style, grammar, terminology)
• linkinator — Dead link detection
• alex — Inclusive writing checker
• markdownlint — Markdown style linting

CI Integration

# .github/​workflows/​docs-lint.yml
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/​checkout@v4
      - run: npx linkinator docs/ --recurse
      - run: npx vale docs/

---

Related Skills

• tl-docs-create — Create documentation from scratch
• tl-docs-viewer-create — React admin UI for browsing docs/ folder