---
name: doc-update
description: Update project documentation based on knowledge gaps discovered during the current session
disable-model-invocation: false
---

# Documentation Update from Session Context

Review the current session to identify knowledge gaps that caused suboptimal codebase
navigation, then update the relevant documentation.

## The quality bar

Every addition must pass this test: **"Would this save a future session at least 5 minutes
of exploration?"**

Documentation serves two purposes — know **where to look** and know **what to do**. Both
are valuable, but at different levels of detail:

- **Navigation map** (good): "Preview flow: `LivePreview.tsx` → `prepareSpecForRender()` (core) → `vega-embed`" — lists the files and their roles so you don't read a dozen files to find the right four.
- **Decision rule** (good): "The fit-mode/reference-resolution transform runs on a _copy_ of the spec — never mutate the stored spec" — captures a non-obvious convention.
- **Code walkthrough** (bad): "SnippetStore.updateDraft sets draftSpec, which a startup subscriber watches, debounces, then calls snippetStore.put… " — restates the code, goes stale on any rename.

**Navigation maps** use file/module names (stable) to show flow direction. **Decision
rules** capture "when/why" constraints. **Code walkthroughs** restate implementation
details — that's what reading the code is for.

For documentation organization, see **[CLAUDE.md](../../../CLAUDE.md)** and the doc index in
**[AGENTS.md](../../../AGENTS.md)**.

## The three documentation layers (know which one a gap belongs to)

- **`docs/spec/`** — the _what_: behavioral contract (what the app does, acceptance points).
  This is a **contract**. Only change it when product behavior genuinely changes, and do so
  deliberately — never as a casual "fill a doc gap" edit. A how-detail does NOT belong here.
- **`docs/architecture/`** — the _how_: the patterns behind each layer (state, persistence,
  modals, routing, rendering, inference, relationships). Most navigation maps and decision
  rules land here.
- **`docs/IMPLEMENTATION-PLAN.md`** — the _when_: milestone sequence and scope.

## Process

### 1. Analyze the session

Look back through the conversation and identify:

- **Missing navigation maps**: Where did you read many files to discover which 3–4 files a
  flow actually involves? A one-line map of file roles would have saved that.
- **Missing rules**: What conventions or constraints were discovered that a new session
  would violate or re-discover?
- **Non-obvious "when/why" knowledge**: What decisions require understanding intent, not
  just implementation?

Produce a brief list of gaps before proceeding. For each, state what's needed in one
sentence — a navigation map ("X flow: file → file → file") or a decision rule ("X must/must
not do Y"). If you can't state it concisely, it may be too implementation-specific to document.

### 2. Categorize and target

Map each gap to the right document:

| Gap type                                          | Target document                                                               |
| ------------------------------------------------- | ----------------------------------------------------------------------------- |
| Product behavior, capabilities, acceptance points | `docs/spec/` (the relevant 00–10 section) — **contract; change deliberately** |
| State / Zustand stores                            | `docs/architecture/01-state-and-stores.md`                                    |
| Persistence, IndexedDB, localStorage, migrations  | `docs/architecture/02-persistence.md`                                         |
| Modals, dialog lifecycle                          | `docs/architecture/03-modal-system.md`                                        |
| URL routing, keyboard/events                      | `docs/architecture/04-routing-and-events.md`                                  |
| Rendering, theming, vega-embed, preview           | `docs/architecture/05-rendering-theming-preview.md`                           |
| Type inference, dataset profiling                 | `docs/architecture/06-type-inference.md`                                      |
| Names, snippet↔dataset links, rename propagation  | `docs/architecture/07-naming-and-relationships.md`                            |
| Milestone scope, build order                      | `docs/IMPLEMENTATION-PLAN.md`                                                 |
| Project philosophy / identity                     | `SOUL.md`                                                                     |
| Onboarding, conventions, stack                    | `AGENTS.md` / `CLAUDE.md`                                                     |

If a gap fits no existing document, consider a new section in the closest one; prefer
extending over creating. A brand-new architecture topic can become `docs/architecture/08-*.md`
(add it to `docs/architecture/00-overview.md`).

### 3. Read, locate, and check for bloat

For each target document:

- Confirm the gap isn't already covered (if partially covered, extend rather than duplicate).
- Find the right insertion point.
- **Check section length**: if a section is already long (>50 lines), tighten or consolidate
  before adding. Documentation that only grows becomes noise.

### 4. Apply updates

- **Rules and constraints over descriptions**: "X must do Y because Z" beats "X works by A, B, C".
- **Matter-of-fact voice**: write what the design _is_ and the standing _why_, not the story
  of how this session arrived at it. No decision-log narration ("this bit us", "we decided",
  "supersedes the earlier plan", "used to do X"), no directives-to-future-self ("keep the
  escape"). Phrase rationale as a standing property of the system, not a resolution reached.
- **Stability over specifics**: no line numbers, no file counts, no volatile details.
- **Proportional**: a missing sentence doesn't need a new section; a missing concept does.
- **Match existing style**: follow surrounding formatting, heading levels, tone.
- **Self-contained**: never add a pointer that requires an external repository to follow.
- **Consolidate while adding**: net size increase should be minimal.

### 5. Update index (if needed)

Only update `CLAUDE.md` (or `docs/architecture/00-overview.md`) if a new document was created
or a major new section was added that should be discoverable. Not for minor additions.

## What NOT to document

- **Code walkthroughs**: prose that restates the code; goes stale on any rename. (Navigation
  maps that list file roles are fine.)
- **TS code blocks that copy current implementation**: a snippet mirroring a real module
  rots on its next rename. An illustrative _shape_ sketch is fine; for real code, point to
  the file (navigation map) or state the rule it demonstrates.
- **Stale-prone references**: positional sub-section cross-refs (`arch 07 §4` renumbers when
  a section is inserted — cite the file `arch 07` or a named section) and exact counts
  (test/file/LOC counts, one-off timings — state the qualitative fact; `codebase-metrics.md`
  owns the tracked numbers).
- **Obvious-from-code patterns**: if reading the file makes it clear, don't add docs.
- **Session-specific context**: current task details, debugging steps taken.
- **Speculative patterns**: only document conventions confirmed across multiple instances.
- **Implementation details that change with refactoring**: if renaming a variable would
  invalidate the doc, it's too specific.