---
description: Audit a repo's docs for drift between README, AGENTS.md, code, declared paths, and reality. Surfaces stale references, broken links, placeholder text, missing required files. Reports Red/Yellow/Green per layer with file:line evidence; never auto-fixes.
---

# personal-doc-audit

Periodic doc-health check. Run on any active repo to catch drift before it embarrasses you.

## Trigger phrases

- "Audit docs in [repo]"
- "Doc health check on [repo]"
- "Is this README accurate?"
- `/doc-audit [path]`

## Layers checked

### Layer 1 — README freshness

- **Last-updated date present?** README files >90 days old often describe a project state that's drifted.
- **Status badge accurate?** "WIP" on a project that's been stable 6 months is misleading. "stable" on a project that hasn't been touched in a year is also misleading.
- **Quick start actually works?** Compare the install/run instructions to actual setup files (package.json scripts, Makefile, etc.) — do they match?
- **Architecture section in sync with code?** If README says "uses PostgreSQL" but `package.json` shows MySQL driver, drift.

### Layer 2 — Internal link validity

- All relative links (`./docs/...`, `../README.md`, etc.) resolve to actual files
- All section anchors (`#installation`) match heading slugs
- All file references in prose actually exist (`see src/foo.ts` — does src/foo.ts exist?)

### Layer 3 — Placeholder text

Grep for:

- `TODO:`, `FIXME:`, `XXX:`
- `[Add your...]`, `<your X here>`, `{{PLACEHOLDER}}`
- `[Description goes here]`
- `Lorem ipsum`

Any hits: surface to Josh for decision.

### Layer 4 — Required file presence

Per repo type, certain files should exist:

| File | scratch | personal-published | portfolio-public |
|---|---|---|---|
| README.md | ✅ | ✅ | ✅ |
| .gitignore | ✅ | ✅ | ✅ |
| LICENSE | optional | ✅ | ✅ |
| AGENTS.md | optional | ✅ | ✅ |
| ARCHITECTURE.md | — | optional | ✅ |
| CHANGELOG.md | — | recommended | ✅ |

Missing files at the appropriate level: surface.

### Layer 5 — AGENTS.md drift

If the repo has AGENTS.md:

- Are the rules still enforced in code? If AGENTS.md says "all subcommands inline in main script" but `tools/` has 5 subcommand files, drift.
- Are paths referenced still accurate?
- Are dependencies named (e.g., "uses Hono") still in package.json?

### Layer 6 — GitHub/GitLab description vs README first-paragraph

If the repo has a remote, the description on the platform should match the README's first paragraph in spirit. Significant drift (description from 6 months ago describing a different project): flag.

### Layer 7 — Project registry sync

If the repo qualifies for inclusion in `~/.config/opencode/AGENTS.md`'s Active Projects Registry:

- Is it listed?
- Does the location match?
- Is the status accurate?

If the repo was deleted but still in the registry: flag.

## Output

```markdown
# Doc Audit — [repo path]

**Audited:** YYYY-MM-DD
**Repo type (inferred):** [scratch | personal-published | portfolio-public]

## Layer-by-layer

### Layer 1 — README freshness
**Status:** 🟢 / 🟡 / 🔴

- [Finding] (file:line if applicable)
- ...

### Layer 2 — Internal links
**Status:** ...

### Layer 3 — Placeholders
**Status:** ...

### Layer 4 — Required files
**Status:** ...

### Layer 5 — AGENTS.md drift
**Status:** ...

### Layer 6 — Description vs README
**Status:** ...

### Layer 7 — Registry sync
**Status:** ...

## Summary

| Layer | Color | Findings |
|---|---|---|
| 1 README | 🟡 | 2 |
| 2 Links | 🟢 | 0 |
| ... | | |

## Recommended actions (highest-leverage first)

1. ...
2. ...

## Findings that are NOT auto-fixable (Josh decision needed)

- ...
```

## Discipline

- **Never auto-fix.** Surface findings; let Josh decide.
- **Surface evidence with file:line.** Vague "the README is out of date" is useless; "README:L3 says 'WIP' but last commit was 8 months ago and is tagged v2.0" is actionable.
- Audit is read-only — no writes.

## Recurring pattern

Recommended cadence: monthly for active repos, quarterly for stable ones. Add to tracker as `INT-DOC-AUDIT-{repo}` recurring item.