Doc Audit

/doc-audit — documentation freshness sweep

Docs rot when nobody verifies them. This skill scans your docs/ directory (or wherever your documentation lives) and flags every doc that's likely stale, drift-prone, or structurally incomplete.

This is not a comprehensive audit (that would take hours). It's a fast triage: find the worst offenders, surface them to the user, recommend actions.

When to use this skill

Invoke when:

• The user is about to ship a feature and wants to verify docs aren't lying
• A new team member is being onboarded and needs trustworthy docs
• It's been a while since the docs were checked (quarterly maintenance)
• The user is investigating a doc-vs-reality discrepancy

If the user wants a deep audit of a specific document, use /verify-claim instead — that's targeted, this is broad.

The protocol

Step 1 — Identify the doc location

Ask if unclear:

> Where do docs live? docs/? Multiple places? Should I include READMEs in subdirectories?

Default: scan docs/ recursively. Include README.md and CONTRIBUTING.md at the repo root if present.

Step 2 — Enumerate the docs

List all markdown files in the doc location:

find docs/ -name '*.md' -type f

Report total count.

Step 3 — Check frontmatter coverage

For each doc, check if it has YAML frontmatter at the top. The required fields are:

• id
• title
• type
• status
• confidence
• last_verified

PRDs additionally need:

• implemented
• target_version (optional)

Report:

Frontmatter coverage:
  Total docs: 47
  With complete frontmatter: 32
  With partial frontmatter: 9
  Without frontmatter: 6

Docs missing frontmatter:
  - docs/notes/random-thoughts.md
  - docs/old-readme.md
  - ...

Step 4 — Check last_verified freshness

For each doc with complete frontmatter, compute days since last_verified.

Buckets:

• Fresh ( 90 days ago` → probably abandoned; flag for cleanup
• status: current + last_verified > 180 days ago → claims currency without verification; flag
• status: superseded without a "see X" link → broken reference; flag

Step 6 — Spot-check code references

For each doc that references specific files or functions (pattern: ` src/... or file.ts:42`), pick a sample of 3-5 references per doc and verify they still exist:

• File path: does the file exist?
• Function name: does grep find it?
• Line number: is it approximately right? (Line numbers drift; don't require exact match.)

For docs with broken references, flag them. Note the specific broken references.

Skip this step if the user asks for a fast scan — it's the most expensive part.

Step 7 — Check audit log presence

For each doc that's structurally non-trivial (PRD, architecture, runbook):

• Does it have an audit log block at the bottom?
• Does the audit log have at least one entry?
• Does the most recent entry match last_verified in frontmatter?

Flag docs that:

• Have no audit log block (and should)
• Have an audit log that hasn't been updated since last_verified

Step 8 — Check for "implemented" drift on PRDs

For each PRD (type: PRD):

• Is implemented set?
• If implemented: false, has the work actually shipped? (Hard to verify automatically; flag for user check.)
• If implemented: true, does the body still describe future tense ("we will build...")? That's drift.

Step 9 — Generate the report

Output a structured report:

# Doc Audit — {date}

## Summary

- Total docs scanned: 47
- Fresh ( Want me to draft the fixes for any of these? I can:
> - Update frontmatter on the docs missing it
> - Add audit log entries for docs you've verified
> - Mark superseded docs explicitly
>
> Pick what you want to address; I'll work through them.

## Example conversation

> **User**: `/doc-audit`
>
> **Assistant**: Scanning `docs/`.
>
> *(Bash: find docs/ -name '*.md' | wc -l)*
>
> Found 34 markdown files in `docs/`. Beginning audit.
>
> *(Reads each file's frontmatter or first 30 lines if no frontmatter detected)*
>
> ...
>
> # Doc Audit — 2026-05-13
>
> ## Summary
>
> - Total docs scanned: 34
> - Fresh: 8
> - Aging: 12
> - Stale: 9
> - Rotten: 5
>
> ## Top priorities
>
> 1. **Rotten**: `docs/PRD-legacy-auth.md` — last verified 11 months ago; status still "current"; references `src/auth/legacy.ts` which was deleted 6 months ago. Recommend: mark `status: superseded` with a link to `PRD-native-auth.md`.
>
> 2. **Broken refs**: `docs/runbook-deploy.md` — references the old CI workflow file path; that file was renamed. Step 4 of the runbook would fail today.
>
> 3. **Missing frontmatter**: 4 docs — `docs/scratch/`, `docs/old-meeting-notes.md`. These look like informal notes; recommend moving them to a `notes/` directory or deleting if obsolete.
>
> ## Recommendations
>
> 1. Tag `PRD-legacy-auth.md` as superseded.
> 2. Update `runbook-deploy.md` steps 4-6 with the new CI path.
> 3. Decide on the scratch docs.
>
> Want me to draft any of these fixes?
>
> **User**: Yes, draft the supersede note for PRD-legacy-auth.md.
>
> *(Edits the file: updates frontmatter status, adds audit log entry, adds a "See PRD-native-auth.md" pointer at the top.)*
>
> Done. Diff is small — `status: current` → `status: superseded`, added a 2-line "Superseded by..." note, and added an audit log entry dated today. Review?

## What to refuse

- **Fixing without showing the user.** Always show the proposed change before applying.
- **Comprehensive deep audits.** This skill is triage. For one-doc deep verification, use `/verify-claim`.
- **Blindly trusting frontmatter.** A doc that says `last_verified: 2026-05-13` may have been edited without anyone verifying. Note that frontmatter is a claim, not a proof.

## When to recommend deprecation over update

A doc is a candidate for deprecation (not update) when:

- It's been rotten for 12+ months with no engagement
- The thing it documents has been replaced
- Maintaining it accurately would take more effort than rewriting

Deprecation note format:

```markdown
> **DEPRECATED:** This document describes the legacy X system. It has been replaced by [Y](Y.md). The contents below are kept for historical context and should not be acted on.

Set status: deprecated in frontmatter. Add an audit log entry.

What "done" means for this skill

• The full audit report has been generated.
• The top priorities are clearly identified.
• The user has decided which to address.
• Any fixes have been applied with user approval.
• Frontmatter and audit logs reflect the work done.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: geigermatic
• Source: geigermatic/claude-craft
• License: MIT

Install and usage instructions live in the source repository linked above.