sync-docs

name	sync-docs
description	Check docs/ai/ spec files and ADRs for inconsistencies with the codebase, then fix all discrepancies.
allowed-tools	Read, Glob, Grep, Agent, Edit, Write, Bash(ls *)

Sync Docs with Codebase

Scan all documentation in docs/ai/ for inconsistencies with the actual codebase, then fix all discrepancies so docs match the implementation.

Scope

Check and fix these doc files:

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

Phase 1: Discover inconsistencies

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

Phase 2: Fix all issues

4. Use TodoWrite to create a task list of all fixes needed.

5. Apply fixes using Edit tool for each doc file. Rules:

   • Always update docs to match the code (code is the source of truth)
   • Keep the existing doc style and structure
   • Write docs in English (matching CLAUDE.md convention)
   • Don't add unnecessary content — only fix what's wrong or missing
   • For ADR status changes, also update docs/ai/adr/INDEX.md

6. Output a summary of all changes made:

## Docs Sync Summary

### [filename]
- [description of fix applied]

### No changes needed
- [filename] — already consistent

Guidelines

• Use parallel Agent tools to speed up codebase exploration
• Be thorough — check every interface field, every param range, every component reference
• Code is always the source of truth; docs adapt to match code
• Preserve existing doc formatting and structure where possible