# audit-docs

> Audits type safety documentation against the live codebase and fixes errors, gaps, or stale information to keep docs authoritative.

- Skill: `joshuashepherd/audit-docs` (Agent Skill)
- Install (CLI): `npx skillmds add joshuashepherd/audit-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/audit-docs/raw
- Safety review: PASS (external: skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing, Security, Technical Writing
- Tags: Api Routes, Codebase, Documentation Audit, Drizzle, React Hooks, Type Safety, Zod
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/audit-docs

---


# Type Safety Documentation Audit & Update

Audit every file in `{{TYPE_DOCS_DIR}}/` against the live codebase and fix any errors, gaps, or stale information so the docs are the authoritative single source of truth for the six-layer type safety chain.

## Before Starting

1. Read every file in `{{TYPE_DOCS_DIR}}/` (README.md, TYPE_SAFETY.md, all files in layers/, validation/, and any other files present).
2. Gather ground truth from the codebase for each layer — use the actual source files, generators, and validators as the authority.

## Ground Truth Collection

For each layer, collect the following from the **actual codebase** (not from existing docs):

### Layer 1 — Drizzle Schema
- Read `{{SCHEMA_PATH}}` (first ~100 lines for structure, then count pgTable exports)
- Read `{{SCRIPTS_DIR}}/validate-db-alignment.ts` to understand what the validator actually checks
- Read `{{SCRIPTS_DIR}}/generate-schema.ts` (if it exists) to understand schema generation
- Count: `grep -c "export const .* = pgTable(" {{SCHEMA_PATH}}`
- Note any tables with type annotations (e.g., `PgTableWithColumns<any>`)

### Layer 2 — Zod Schemas
- Read `{{SCHEMAS_DIR}}/index.ts` (first ~80 lines for structure, imports, BaseFiltersSchema)
- List other files in `{{SCHEMAS_DIR}}/` (custom schemas)
- Read `{{SCRIPTS_DIR}}/generate-zod-schemas.ts` (first ~100 lines for pattern)
- Read `{{SCRIPTS_DIR}}/validate-semantic-alignment.ts` to understand validation logic
- Note the four-schema pattern and type exports

### Layer 3 — Services
- Read `{{SERVICES_DIR}}/base.service.ts` for the Result<T> pattern, class signature, and methods
- Sample one entity service file for the actual pattern
- List `src/lib/services/custom/` contents
- Read `{{SCRIPTS_DIR}}/generate-services.ts` (first ~80 lines)
- Read `{{SCRIPTS_DIR}}/validate-services-alignment.ts`

### Layer 4 — API Routes
- Sample one route file from `{{API_DIR}}/` for the actual handler pattern
- List `src/app/api/custom/` directories
- Read `{{SCRIPTS_DIR}}/generate-routes.ts` (first ~80 lines)
- Read `{{SCRIPTS_DIR}}/validate-routes-alignment.ts`

### Layer 5 — React Hooks
- Sample one hook file from `{{HOOKS_DIR}}/` for the actual pattern (keys, hooks, fetchApi, buildQueryString)
- List `{{HOOKS_DIR}}/custom/` contents
- Read `{{SCRIPTS_DIR}}/generate-hooks.ts` (first ~80 lines)
- Read `{{SCRIPTS_DIR}}/validate-hooks-alignment.ts`
- Check `src/app/providers.tsx` for QueryClientProvider

### Layer 6 — UI Components
- Sample one component from `{{COMPONENTS_DIR}}/simplified/` for the actual pattern
- Read `{{SCRIPTS_DIR}}/generate-ui-components.ts` (first ~80 lines)
- Read `{{SCRIPTS_DIR}}/validate-ui-alignment.ts`

### Cross-Cutting
- Read `{{CONFIG_PATH}}` (first ~30 lines) for tenant scoping context
- Read `src/lib/tenant.ts` for getTenantOrgId
- Count entities at each layer to verify consistency

## Audit Checklist

Compare every claim in the docs against ground truth. Flag and fix:

1. **Incorrect counts** — table counts, entity counts, file counts
2. **Wrong patterns** — code examples that don't match actual generated code
3. **Missing information** — layers, patterns, or conventions not documented
4. **Stale references** — files, paths, or commands that no longer exist
5. **Naming convention errors** — incorrect camelCase/PascalCase/kebab-case mappings
6. **Validator behavior** — what each validator actually checks vs. what docs claim
7. **Generator behavior** — what each generator does (overwrites vs. skips existing) vs. what docs claim
8. **Custom code gaps** — custom services, hooks, routes not mentioned or incorrectly described
9. **contentCategories discrepancy** — verify the 148 vs 147 explanation is still accurate
10. **Lock-Before-Proceed protocol** — ensure the protocol description matches actual validator exit codes and workflow
11. **Commands** — ensure all pnpm commands listed match package.json
12. **Cross-references** — ensure layer docs reference each other correctly

## Update Rules

- Fix errors in place — do not create new files unless a section genuinely needs its own file
- Use actual code snippets from the codebase, not invented examples
- Keep the same document structure and voice — just make it accurate
- Update counts, paths, patterns, and examples to match reality
- If a doc file covers something that no longer exists, remove that section
- If the codebase has something undocumented, add it to the appropriate doc
- Update `{{TYPE_DOCS_DIR}}/validation/VALIDATION_STATUS.md` with current actual status (run validators if possible)
- Update the README.md index if any files were added or removed

## After Updating

1. Review each updated file for internal consistency
2. Ensure no doc references a pattern that contradicts another doc
3. Verify all code examples are syntactically correct
4. Confirm the README.md index accurately lists all files in `{{TYPE_DOCS_DIR}}/`