update-docs

Update Docs Skill

Update README.md files in the folders where code was changed. Documentation lives next to the code it describes — each component/abstraction folder has its own README.

When to Use

Activate this skill when:

• The user explicitly asks to update documentation after changes
• After completing a task that adds, removes, or significantly modifies files in a component/abstraction folder

Principles

1. Co-located — Each README lives in the folder it documents
2. Lean — Only document what helps a developer understand the folder's purpose, structure, and patterns
3. Precise — Accurate file names, sizes, type counts, and descriptions
4. Compact — No verbose prose. Use tables, bullet points, and code snippets
5. Delta-driven — Only update sections affected by the change. Don't rewrite unrelated content

README Structure Convention

Each folder's README follows this skeleton (sections included only when relevant):

# folder-name/ - Short Purpose

One-sentence overview. Contains **N files**.

## Architecture
[Only if the folder has a non-obvious entry point, router, or coordination pattern]

## Components / Modules / Types
[Table or bullet list of files with one-line descriptions]

## Pattern
[Code snippet showing the common pattern, if one exists]

What to Document

Change Type	Documentation Action
New file added	Add entry to the file list with one-line description
File removed	Remove entry from the file list
File renamed	Update the entry
New pattern introduced	Add/update the Pattern section
Architecture change	Update the Architecture section
File count changed	Update the count in the overview line
New block/menu/popup type	Add to the relevant type list

What NOT to Document

• Implementation details that are obvious from reading the code
• Function-level API docs (that's what the code and types are for)
• Changelog/history of what changed when
• TODO items or future plans
• Descriptions longer than one sentence per file
• Redundant information already in CLAUDE.md

Process

1. Identify affected folders — Determine which folders had files added, removed, or significantly changed
2. Read existing README — Check if a README.md exists in each affected folder
3. Determine delta — Compare the change against what the README currently says
4. Apply minimal update — Edit only the affected lines/sections
5. Verify accuracy — Ensure file names, counts, and descriptions match reality

Scope Rules

• Only update READMEs in folders where code actually changed
• If a folder has no README yet and the change is significant (new subfolder, new abstraction layer), create one following the convention
• If the change is trivial (typo fix, minor logic tweak), skip documentation update
• Never update CLAUDE.md from this skill — that file has its own maintenance process

Examples

File added to block/

Change: Added `src/ts/component/block/ai.tsx`

Action: Edit `src/ts/component/block/README.md`
- Update file count in overview line
- Add entry under "Other Blocks":
  - `ai.tsx` - AI-generated content block

New store added

Change: Added `src/ts/store/theme.ts`

Action: Edit `src/ts/store/README.md`
- Add row to the Stores table:
  | `theme.ts` | `S.Theme` | Theme management: color schemes, dark mode preferences |

File removed from menu/

Change: Removed `src/ts/component/menu/legacySearch.tsx`

Action: Edit `src/ts/component/menu/README.md`
- Remove entry for legacySearch from the menu types list
- Update count if mentioned

New subfolder created

Change: Created `src/ts/component/block/ai/` with index.tsx, toolbar.tsx, preview.tsx

Action: Create `src/ts/component/block/ai/README.md`:
  # ai/ - AI Content Block

  AI-generated content blocks with toolbar controls and preview. Contains **3 files**.

  ## Files
  - `index.tsx` - Main block component, renders AI content with edit/regenerate actions
  - `toolbar.tsx` - Prompt input and model selection toolbar
  - `preview.tsx` - Streaming preview of AI-generated content

Also update parent `src/ts/component/block/README.md` to reference the new subfolder.