maintenance
Documentation self-maintenance rules. Auto-applied after any code change to ensure docs, skills, and feature lists stay in sync with the codebase.
SKILL.mdAutoAnimation/.claude/skills/maintenance/SKILL.md
GitHubDocumentation Self-Maintenance
After EVERY code change, check and update affected documentation. Treat documentation as code — it ships with the commit.
Documentation Registry
These are the living documents that must stay in sync with the codebase:
| File | Purpose | When to Update |
|---|---|---|
CLAUDE.md |
Project overview, structure map, skills reference | New directories, new skills, tech stack changes |
docs/feature-list.md |
Master list of all user-facing features (currently 160) | Any new feature added or existing feature removed |
docs/tabs.md |
Tab groups, sub-tabs, panel organization | Any tab added, removed, renamed, or reorganized |
docs/PROGRESS.md |
Session progress and pending items | Features completed, bugs fixed, new pending items |
.claude/skills/*/SKILL.md |
Skill-specific workflows | Referenced files moved/renamed, APIs changed, new steps added |
.claude/skills/architecture/SKILL.md |
Project architecture | New directories, new architectural patterns, tech stack changes |
.claude/skills/patterns/SKILL.md |
Coding conventions | New patterns adopted, naming conventions changed |
docs/codebase/*.md |
Per-section API reference (functions, stores, components) | Any function/store/component/hook added, removed, or renamed |
Update Rules by Change Type
1. New Feature Added
docs/feature-list.md → Add numbered entry (increment count in header)
docs/tabs.md → Add tab entry if feature has a panel
CLAUDE.md → Update Project Structure if new directory created
Relevant skill SKILL.md → Update Key Files or Steps if skill covers this area
2. New Panel/Tab Created
docs/tabs.md → Add to correct group with id, label, icon, description
docs/feature-list.md → Add feature entry if not already listed
3. New Store/Service/Component Created
CLAUDE.md → Only if it creates a new directory pattern
Architecture SKILL.md → If it introduces a new architectural concept
Patterns SKILL.md → If it establishes a new coding pattern
4. Feature Modified or Refactored
Relevant skill SKILL.md → Update steps, file paths, function names
docs/feature-list.md → Update description if behavior changed
5. File Moved or Renamed
ALL skills that reference the old path → Update file paths
CLAUDE.md → Update Project Structure if directory changed
6. Bug Fixed
docs/PROGRESS.md → Add to completed section with fix description
7. New Skill Created
CLAUDE.md → Add to Skills Reference table in correct category
8. Tab Reorganized
docs/tabs.md → Reflect new group structure
How to Update docs/feature-list.md
- Entries are numbered:
1. **Feature Name** — One-line description - Keep the count in the header accurate:
160 user-facing features. - Group by area (characters, rigging, audio, AI, canvas, export, etc.)
- One line per feature, bold name, em-dash, description
How to Update docs/tabs.md
- Format:
- \tab-id` — Label — Description` - Grouped under numbered sections matching
tabGroups.tsgroup IDs - Include sub-tab count per group in the heading
Stale Reference Detection (MANDATORY)
After ANY code change — even small ones — run a stale reference scan before committing. This catches renamed functions, moved files, changed parameters, and modified store interfaces that docs still reference by the old name.
Step 1: Identify what changed
Look at the files you modified. Extract the key identifiers: file names, exported function names, store names, type names, interface properties, API endpoints.
Step 2: Grep docs for stale references
For each changed/renamed/removed identifier, search ALL documentation:
# Search all skills and docs for references to a changed file or function
rg "oldFunctionName\|oldFileName\|oldStoreName" .claude/skills/ docs/ CLAUDE.md
Run this for:
- Renamed files:
rg "oldFileName" .claude/skills/ docs/ CLAUDE.md - Renamed functions/exports:
rg "oldFunctionName" .claude/skills/ docs/ - Changed store interfaces (added/removed/renamed fields):
rg "useXxxStore" .claude/skills/ - Changed API endpoints:
rg "/api/old-endpoint" .claude/skills/ docs/ - Renamed types/interfaces:
rg "OldTypeName" .claude/skills/
Step 3: Update every hit
Every grep result is a stale reference that MUST be updated. No exceptions.
Examples of small changes that need doc updates
| Change | What goes stale |
|---|---|
Rename silenceDetection.ts → silenceDetector.ts |
smart-cut/SKILL.md references old filename |
Rename processAlignment() → convertAlignment() |
generate-voice/SKILL.md references old function |
Add threshold param to detectSilence() |
smart-cut/SKILL.md missing new parameter |
Change store field items → elements |
Any skill referencing store.items |
Move src/services/foo.ts → src/services/audio/foo.ts |
All skills referencing old path |
| Remove an export from a service | Skills that tell Claude to use that export |
Change API route /api/whisper → /api/transcribe |
transcript-edit/SKILL.md, architecture skill |
Rename tab ID voice-clone → clone-voice |
docs/tabs.md, add-panel/SKILL.md |
When NOT to scan
Skip the scan only if your change is:
- Purely internal logic (no renamed exports, files, types, or interfaces)
- CSS/styling only
- Console.log additions/removals
- Comment changes
If in doubt, scan. It takes 2 seconds and catches real problems.
Commit Pattern
Always include doc updates in the SAME commit as the code change:
git add src/services/newFeature.ts src/stores/useNewFeatureStore.ts docs/feature-list.md docs/tabs.md
git commit -m "Add new feature X with panel and store"
Never make a separate "update docs" commit after a code change.
Verification Checklist
Before committing, run through:
- Stale reference scan done? →
rg "changedIdentifier" .claude/skills/ docs/ CLAUDE.md - Did I add a new feature? →
docs/feature-list.mdupdated? - Did I add a new panel/tab? →
docs/tabs.mdupdated? - Did I change files referenced by a skill? → Skill SKILL.md updated?
- Did I fix a bug or complete a pending item? →
docs/PROGRESS.mdupdated? - Did I create a new skill? →
CLAUDE.mdSkills Reference updated? - Did I change project structure? →
CLAUDE.mdProject Structure updated?