check-docs

name	check-docs
description	Check docs/ai/ spec files and ADRs for inconsistencies with the actual codebase. Report only, no modifications.
allowed-tools	Read, Glob, Grep, Agent, Bash(ls *)

Check Docs Consistency

Scan all documentation in docs/ai/, site docs, and app help for inconsistencies with the actual codebase. Do not modify any files.

Scope

Check these doc files against implementation:

Root docs

1. README.md — project description, feature list, tech stack, project structure

AI / internal docs (docs/ai/)

2. CLAUDE.md — project description, build commands, conventions, key architecture notes
3. docs/ai/BACKLOG.md — check completed items against code, remove if done
4. docs/ai/architecture.md — ADR statuses, component list, directory structure, commands
5. docs/ai/overview.md — current state, non-goals
6. docs/ai/sequencer-spec.md — Pattern/Track/Trig interfaces, playback behavior
7. docs/ai/audio-interface.md — WorkletCommand, WorkletPattern, WorkletTrig, Engine API
8. docs/ai/sound-design.md — voice params, paramDefs ranges/defaults
9. docs/ai/ui-design.md — component descriptions, layout, mobile views
10. docs/ai/glossary.md — term accuracy, missing terms
11. docs/ai/DATA_MODEL.md — Song/Pattern/Cell/Track/Trig interfaces, relationships, mermaid ERD entity fields and classDiagram runtime state fields
12. docs/ai/MESSAGE_FLOW.md — WorkletCommand flow, message protocol, signaling, mermaid sequence diagram function names
13. docs/ai/adr/INDEX.md — ADR statuses (Implemented vs actual state)
14. All ADR files marked as "Implemented" in INDEX.md — check against code

Site docs (site/src/content/docs/)

15. All .mdx files under site/src/content/docs/docs/ (EN) and site/src/content/docs/ja/docs/ (JA) — tutorials, feature guides, getting-started pages
16. Feature descriptions must match current implementation (e.g. number of FX slots, available parameters, signal flow)
17. EN and JA versions must stay in sync with each other

App help (src/lib/components/SidebarHelp.svelte)

18. Help card text — feature descriptions, parameter lists, workflow descriptions

Process

1. Read all doc files listed above.

2. Cross-reference with codebase by reading/grepping these key source files:

   • src/lib/types.ts — Song, Pattern, Cell, Trig, Track interfaces
   • src/lib/state.svelte.ts — reactive state shape
   • src/lib/audio/engine.ts — Engine API, patternToWorklet serialization
   • src/lib/audio/dsp/types.ts — WorkletCommand, WorkletPattern, WorkletTrig, WorkletInsertFx
   • src/lib/audio/worklet-processor.ts — WorkletCommand handling
   • src/lib/paramDefs.ts — voice parameter definitions (names, ranges, defaults)
   • src/lib/components/*.svelte — component names and existence
   • src/lib/audio/dsp/voices.ts — voice registry
   • src/lib/components/SidebarHelp.svelte — app help text

3. Check for these types of inconsistencies:

   • Type/interface field mismatches (missing fields, wrong field names, wrong types)
   • Mermaid diagrams: treat erDiagram entity fields and classDiagram class fields as structured data — compare every field name, type, and description 1:1 against the source TypeScript interfaces (DATA_MODEL.md ERD vs types.ts, classDiagram vs state.svelte.ts, MESSAGE_FLOW.md sequence diagrams vs actual function names in scenePlayback.ts / engine.ts)
   • Wrong parameter ranges or defaults in docs vs paramDefs.ts
   • Components mentioned in docs that don't exist, or existing components not documented
   • ADR status mismatches (doc says PROPOSED but feature is implemented, or vice versa)
   • Removed/renamed features still documented
   • Missing documentation for implemented features
   • Stale line-number references to source files

4. Output a report in this format:

## Docs Consistency Report

### [filename]
- **[section]**: [description of inconsistency]
  - Doc says: [what the doc states]
  - Code says: [what the code actually does]

### No issues found
- [filename] — OK

Guidelines

• Use parallel Agent tools to speed up codebase exploration
• Be thorough — check every interface field, every param range, every component reference
• Only report confirmed inconsistencies, not stylistic preferences
• Group findings by file for easy reference
• This is a READ-ONLY operation — do not edit any files