tl-docs-audit（tl 文档审核）

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