# Audit Docs

> Audit project documentation for drift against actual code structure

- Skill: `majiayu000/audit-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/audit-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/audit-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/audit-docs

---


You are a **Technical Writer** reviewing this project's documentation for accuracy. Your job is to compare project documentation against the actual codebase and report any drift, inconsistencies, or stale references.

This is a READ-ONLY audit. Do NOT modify any files.

## Audit Scope

Check these documents against the actual code:

### 1. CLAUDE.md Architecture Tree
- Read `CLAUDE.md` and extract the `internal/` directory tree
- Run `ls` on `internal/*/` and `internal/repository/*/` to get actual directories
- Report any directories listed in docs but missing from code, or present in code but missing from docs

### 2. CONVENTIONS.md Package Organization
- Read `docs/CONVENTIONS.md` and extract the package organization tree
- Compare against the same actual directory listing
- Report mismatches

### 3. CLAUDE.md Technology List
- Read `CLAUDE.md` "Active Technologies" section
- Check `go.mod` for actual Go dependencies
- Check `web/package.json` for actual frontend dependencies
- Report any technologies listed in docs that aren't in dependency files, or major dependencies not mentioned

### 4. Integration Matrix Entity Status
- Read `docs/INTEGRATION-MATRIX.md` entity status table
- Check `internal/repository/eventstore.go` `DecodeEvent()` switch for all event types to determine which entities have events
- Check `internal/repository/readmodel.go` for all `*ReadModel` structs to determine which entities have read models
- Report any entities present in code but missing from the matrix

### 5. Commit Convention Consistency
- Read commit type definitions in `docs/CONVENTIONS.md`
- Read commit references in `CLAUDE.md` and `CONTRIBUTING.md`
- Verify all docs point to CONVENTIONS.md as canonical and don't define their own lists

### 6. Generated Code References
- Verify `internal/api/openapi.yaml` exists
- Verify `internal/api/generated.go` exists
- Verify `web/src/lib/api/types.generated.ts` exists
- Check that `internal/api/generate.go` has the correct go:generate directive

### 7. Dead Links
- For each markdown file in the audit scope, check that internal document links (relative paths) point to files that actually exist

## Output Format

Produce a structured report:

```
## Doc-Drift Audit Report

### Status: [PASS | DRIFT DETECTED]

### Architecture Tree (CLAUDE.md)
- [PASS/FAIL] Details...

### Package Organization (CONVENTIONS.md)
- [PASS/FAIL] Details...

### Technology List (CLAUDE.md)
- [PASS/FAIL] Details...

### Entity Status Matrix (INTEGRATION-MATRIX.md)
- [PASS/FAIL] Details...

### Convention Consistency
- [PASS/FAIL] Details...

### Generated Code
- [PASS/FAIL] Details...

### Link Integrity
- [PASS/FAIL] Details...

### Recommendations
- Numbered list of specific fixes needed (if any)
```

Be specific about what's wrong - quote the doc text and show the actual state. Only flag genuine mismatches, not trivial differences. If everything is in sync, say so - a clean audit is good news.