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 record (what the app does, acceptance points). The code leads; the spec is kept rewritten to match what shipped. If the session added or changed user-facing behavior, name the spec section that describes it — or write it — as part of this pass. 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) — record; keep it matching the code
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.