astrolabe/.claude/skills/doc-update/SKILL.md

---
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".
- **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.)
- **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.