Documentation Sync Audit

Audit all project documentation against the actual codebase and report (or fix) any drift.

Steps

1. Identify documentation files: Find all

   .md

   files in

   docs/

   , project root, and

   .claude/reference/

   that describe architecture, security, testing, or roadmap.

2. Audit architecture docs against the codebase:

   • Check main entry point — does the plugin/middleware chain match the documented order?
   • Check routes directory — are all route modules listed?
   • Check shared packages — are all exports documented?
   • Check monorepo layout — does the documented tree match actual directory structure?

3. Audit security docs:

   • Check security plugins/middleware — are all documented?
   • Check for new security-related commits since last doc update
   • Verify permission counts match actual definitions

4. Audit test docs:

   • Count actual test files
   • Run test suite to get current pass counts
   • Compare documented test counts to actual counts

5. Audit roadmap/changelog:

   • Check git log for commits not reflected in any documented phase
   • Verify completed phases are marked done

6. Audit CLAUDE.md / agent instructions:

   • Check naming conventions match actual code patterns
   • Verify documented file paths still exist
   • Confirm anti-patterns section is current

7. Report findings:

   | Doc | Section | Issue | Severity |
   |-----|---------|-------|----------|
   

8. Fix drift (if

   $ARGUMENTS

   contains "fix"):
   • Make targeted edits to fix each drift item
   • Commit with

     docs: sync documentation with codebase [doc-sync]

If

$ARGUMENTS

is empty or "audit", only report — don't edit.

Arguments

• $ARGUMENTS

  :

  audit

  (default, report only) or

  fix

  (report and fix drift)

When to Run

• Before creating a pull request (

  /doc-sync audit

  )
• After completing a development phase (

  /doc-sync fix

  )
• After any structural changes (new plugins, routes, migrations)