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

name, description, disable-model-invocation

name	description	disable-model-invocation
doc-update	Update project documentation based on knowledge gaps discovered during the current session	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 and the doc index in 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.