update

name	update
description	Incrementally update an existing code-to-docs vault after coding changes. Diffs against the last documented commit, re-analyzes only affected modules, merges with existing docs, and tracks issue resolution. Use when someone says update docs, sync docs, refresh documentation, or after making code changes.

Overview

Run an incremental documentation update instead of a full generation. Reads _state/analysis.json from the existing vault, diffs against the stored commit, re-analyzes only affected modules, and merges results with existing docs.

Related Skills

Skill	Purpose
code-to-docs	Full generation (quick or full mode) — use when no vault exists yet
code-to-docs:digest	Load existing vault context before coding (read-only)

Invocation

Skill(skill: "code-to-docs:update", args: "<path> [--output <path>]")

• <path> — codebase root (default: . current directory)
• --output — vault path containing the existing _state/analysis.json (default: ./docs-vault/)

Prerequisites

• An existing vault with _state/analysis.json at the output path
• The codebase must be a git repository (needed for git diff)
• If either is missing, fall back to a full generate run and inform the user

---

Model Tiers

Same tiers as code-to-docs — see that skill for the full table. Key rule: use the cheapest model that meets the task's cognitive demand. Haiku for extraction/mechanical, Sonnet for writing, Opus only for complex modules or large codebase synthesis.

---

Execution

Read ../code-to-docs-references/analysis-guide.md section "Incremental Update Flow" for detailed step-by-step instructions. Read ../code-to-docs-references/output-structure.md for state file schema and vault layout. Read ../code-to-docs-references/obsidian-templates.md for formatting rules.

Step 1: Load and Validate Previous State

1. Read _state/analysis.json from the existing vault at --output path
2. If the file does not exist, abort update and fall back to a full generate run. Inform the user: "No previous state found — running full generation instead."
3. Validate the state file against the schema in ../code-to-docs-references/output-structure.md "State File Validation" section. If required fields are missing or have wrong types, report the validation error and fall back to a full generate run.
4. Extract: git_commit (the commit hash from the last run), modules (module list), dependency_graph, files_analyzed, issues

Step 2: Diff

1. Run git diff <stored_git_commit>..HEAD --name-only in the codebase root
2. Filter out excluded paths (see ../code-to-docs-references/analysis-guide.md Exclusions section)
3. The result is the list of changed files since the last documentation run

If the diff is empty (no changes since last run), report "No changes since last documentation run" and exit without modifying the vault.

Step 3: Map Changes to Modules

For each changed file, look it up in the files_analyzed map to determine which module it belongs to.

Classify the changes:

Category	Detection	Implication
Modified within existing module	Changed file found in files_analyzed for a known module	Re-analyze that module
New file in existing module directory	File path falls within a known module's root path but is not in files_analyzed	Re-analyze that module
New file outside all modules	File path is not in any known module's root path	Potential new module — triggers full mode
Deleted file	File in files_analyzed no longer exists on disk	Re-analyze the owning module
New top-level directory with source files	New directory at project root containing code files	New module — triggers full mode

Build the list of affected modules — modules that need re-analysis.

Step 4: Auto-Select Mode

Condition	Mode
All changes within existing modules, no new modules, no deleted modules	Quick
New module detected (new directory with source files outside existing module roots)	Full
Module deleted (all files in a module removed)	Full
Dependency structure changed (new cross-module imports detected in diff)	Full
>50% of tracked files in files_analyzed changed	Full

Report the auto-selected mode to the user: "Update mode: quick (2 of 8 modules affected)" or "Update mode: full (new module detected: Scheduler)".

Step 5: Re-Analyze Affected Modules

For each affected module, run the same two-pass analysis as baseline:

1. Haiku extraction (sections 1-6) — same agent prompt template as ../code-to-docs-references/analysis-guide.md Pass 1
2. Sonnet/Opus issue analysis (section 7) — same agent prompt template as ../code-to-docs-references/analysis-guide.md Pass 2, same model escalation rules

For unchanged modules, carry forward their existing reports from the previous run. Do not re-analyze.

If auto-selected mode is full, also run Module Identification to detect any new modules, then analyze those as well.

Step 6: Merge Synthesis

Combine new analysis reports (affected modules) with carried-forward reports (unchanged modules) into a single synthesis.

1. Rebuild dependency graph from all module reports (new + carried forward)
2. Compare new dependency graph to previous — flag any structural changes
3. Regenerate architecture narrative (always — even small changes can shift the system story)
4. Merge issues:
   • Issues in re-analyzed modules: replace with new analysis results
   • Issues in unchanged modules: carry forward with status open
   • Issues from previous run that no longer appear in re-analyzed modules: mark as resolved

Step 7: Selective Generation

Use the same Phase 2 generation flow as code-to-docs, but selectively:

Output	When to regenerate
Architecture/System Overview.md	Always (cross-module, cheap to regenerate)
Architecture/Dependency Map.md	Always
Architecture/System Map.canvas	Always
Modules/{Name}.md for affected modules	Always
Modules/{Name}.md for unchanged modules	Never — preserve existing
Health/ (all files)	Always (depends on merged issues)
Patterns/ (full mode)	Only if auto-selected full
Onboarding/ (full mode)	Only if auto-selected full
Cross-Cutting/ (full mode)	Only if auto-selected full
Index.md	Always (cheap, ensures consistency)
_state/analysis.json	Always (must reflect new state)

Step 8: Update State File

Write _state/analysis.json with:

• git_commit → current HEAD
• timestamp → now
• mode → the auto-selected mode
• modules → merged module list (may include new modules in full mode)
• files_analyzed → merged map (updated entries for re-analyzed modules, carried forward for unchanged)
• issues → merged array with status updates
• sessions → append new session entry (see ../code-to-docs-references/output-structure.md for schema)

Step 9: Verify

Same as code-to-docs Phase 3 — Haiku agent checks wikilinks and frontmatter across the entire vault (not just changed files).

---

Issue Tracking Across Updates

On each update, compare the new issues against the previous issues array:

Scenario	Action
Issue from previous run still present in re-analyzed module	Keep with status open
Issue from previous run absent in re-analyzed module	Change status to resolved
Issue from previous run in a module that wasn't re-analyzed	Keep with status open (unchanged)
New issue found in re-analyzed module	Add with status open

---

Red Flags

1. Re-analyzing unchanged modules — only affected modules get re-analyzed
2. Skipping state file validation — always validate before reading
3. Ignoring the auto-select mode logic — don't always run quick or always run full
4. Deleting unchanged module docs — preserve them, only regenerate affected ones
5. All red flags from code-to-docs also apply during the re-analysis phases