audit-docs

What problem does it solve?

Project documentation often diverges from the actual repository state, causing onboarding friction, incorrect developer assumptions, and broken build or deployment expectations. This Skill performs a focused, read-only comparison between documentation and code to surface missing files, stale technology lists, inconsistent convention references, and broken internal links.

Core Features & Use Cases

• Architecture Tree Comparison: Extracts the internal/ directory tree described in CLAUDE.md and compares it to the actual internal/* and internal/repository/* directory listings to find missing or undocumented directories.
• Package & Technology Verification: Compares technologies listed in CLAUDE.md and CONVENTIONS.md against go.mod and web/package.json to detect undocumented or stale dependencies.
• Entity Matrix & Generated Code Checks: Cross-references docs/INTEGRATION-MATRIX.md with event types in internal/repository/eventstore.go and read model structs in internal/repository/readmodel.go, and verifies presence of internal/api/openapi.yaml, internal/api/generated.go, and web/src/lib/api/types.generated.ts.
• Link Integrity and Convention Consistency: Validates relative markdown links within the audited docs and checks that commit/convention references point to docs/CONVENTIONS.md as canonical.
• Use Case Example: A technical writer or maintainer runs the audit before a release to ensure docs, API artifacts, and dependency lists are accurate.

Quick Start

Perform a read-only audit that compares CLAUDE.md, docs/CONVENTIONS.md, docs/INTEGRATION-MATRIX.md, go.mod, web/package.json, internal/ and internal/repository/ directory contents, and generated API artifacts, then produce the structured Doc-Drift Audit Report.