Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

perf(understand): avoid unnecessary agents on incremental updates

Lum110456f47f2ab3bc
diff --git a/tests/skill/understand/test_incremental_skill_contract.test.mjs b/tests/skill/understand/test_incremental_skill_contract.test.mjs
new file mode 100644
index 00000000..33aabf2a
--- /dev/null
+++ b/tests/skill/understand/test_incremental_skill_contract.test.mjs
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skill = readFileSync(
+ resolve(__dirname, '../../../understand-anything-plugin/skills/understand/SKILL.md'),
+ 'utf-8',
+);
+const hook = readFileSync(
+ resolve(__dirname, '../../../understand-anything-plugin/hooks/auto-update-prompt.md'),
+ 'utf-8',
+);
+
+describe('incremental execution contract', () => {
+ it.each([skill, hook])('routes inventory and baseline updates through bundled helpers', content => {
+ expect(content).toContain('prepare-incremental.mjs');
+ expect(content).toContain('finalize-incremental.mjs');
+ expect(content).toContain('filesToReanalyze');
+ expect(content).toContain('batch-existing.json');
+ expect(content).toContain('generated-artifact-only');
+ });
+
+ it('skips whole-graph LLM phases for ordinary partial updates', () => {
+ expect(skill).toContain('Both incremental actions skip assemble-reviewer');
+ expect(skill).toContain('For `PARTIAL_UPDATE`, dispatch no architecture agent');
+ expect(skill).toContain('For `PARTIAL_UPDATE`, dispatch no tour agent');
+ expect(skill).toContain('Without `--review`');
+ expect(skill).toContain('Do not run Phase 6');
+ });
+
+ it('keeps explicit review and architecture escalation behavior', () => {
+ expect(skill).toContain('The user-facing `--review` option is still honored');
+ expect(skill).toContain('where `rerunArchitecture === true`');
+ expect(skill).toContain('where `rerunTour === true`');
+ expect(skill).toContain('`FULL_UPDATE`');
+ });
+});
diff --git a/tests/skill/understand/test_skill_security_snippets.test.mjs b/tests/skill/understand/test_skill_security_snippets.test.mjs
index 35117fd3..0f608d07 100644
--- a/tests/skill/understand/test_skill_security_snippets.test.mjs
+++ b/tests/skill/understand/test_skill_security_snippets.test.mjs
@@ -44,12 +44,9 @@ describe('skill command hardening', () => {
'understand-anything-plugin/hooks/auto-update-prompt.md',
);
- expect(content).toMatch(
- /Before filtering by extension, remove every path under the selected `\$UA_DIR`/,
- );
- expect(content).toMatch(
- /If no paths remain after removing `\$UA_DIR`[\s\S]*without writing `meta\.json`/,
- );
+ expect(content).toContain('generated-artifact-only');
+ expect(content).toContain('intentionally advances nothing for generated-only commits');
+ expect(content).toContain('Never update `meta.json` for a generated-artifact-only commit');
});
it('quotes dashboard cd targets and GRAPH_DIR assignment', () => {
diff --git a/understand-anything-plugin/hooks/auto-update-prompt.md b/understand-anything-plugin/hooks/auto-update-prompt.md
index 5ad13509..94a75f5c 100644
--- a/understand-anything-plugin/hooks/auto-update-prompt.md
+++ b/understand-anything-plugin/hooks/auto-update-prompt.md
@@ -1,328 +1,99 @@
# Auto-Update Knowledge Graph (Internal — Hook-Triggered)
-Incrementally update the knowledge graph using deterministic structural fingerprinting to minimize token usage. This prompt is triggered automatically by the post-commit hook when `autoUpdate` is enabled. It is NOT a user-facing skill.
+Incrementally update the knowledge graph after a commit. Do not ask the user for confirmation.
-**Key principle:** Spend zero LLM tokens when changes are cosmetic (formatting, internal logic). Only invoke LLM agents when structural changes (new/removed functions, classes, imports, exports) are detected.
+**Cost rule:** deletion-only, ignored-only, generated-artifact-only, and cosmetic-only updates dispatch no LLM agent. Local structural updates dispatch file-analyzer only for the current files that actually changed structurally. Whole-graph architecture/tour agents run only when the prepared plan requests them.
----
+## Phase 0 — Pre-flight and deterministic preparation
-## Phase 0 — Pre-flight (Zero Token Cost)
+1. Set `PROJECT_ROOT` to the current working directory. Resolve the data directory once:
-1. Set `PROJECT_ROOT` to the current working directory. **Resolve the data directory `$UA_DIR`** once and reuse it for every read and write below: `UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"` — this selects the legacy `.understand-anything/` when it already exists, otherwise the new `.ua/`. Because each phase may run in a fresh shell, carry `$UA_DIR` forward like `$PROJECT_ROOT`, re-resolving it with the same line if a later command block needs it. Scripts written below that run in Node resolve the same rule in JavaScript.
-
-2. Check that `$UA_DIR/knowledge-graph.json` exists.
- - If not: report "No existing knowledge graph found. Run `/understand` first to create one." and **STOP**.
-
-3. Check that `$UA_DIR/meta.json` exists and read `gitCommitHash`.
- - If not: report "No analysis metadata found. Run `/understand` to create a baseline." and **STOP**.
-
-4. Get current commit hash:
```bash
- git rev-parse HEAD
+ UA_DIR="$PROJECT_ROOT/$([ -d "$PROJECT_ROOT/.understand-anything" ] && echo .understand-anything || echo .ua)"
```
-5. If commit hashes match and `--force` is NOT in `$ARGUMENTS`: report "Knowledge graph is already up to date." and **STOP**.
+2. Require `$UA_DIR/knowledge-graph.json` and `$UA_DIR/meta.json`. If either is missing, report that `/understand` must create a baseline and **STOP**.
+3. Read `gitCommitHash` from meta as `$LAST_COMMIT_HASH`; get `$HEAD_COMMIT` with `git rev-parse HEAD`. If they match, report that the graph is current and **STOP**.
+4. Resolve `$PLUGIN_ROOT` from `$CLAUDE_PLUGIN_ROOT`, then `$HOME/.understand-anything-plugin`, validating that it contains `skills/understand/prepare-incremental.mjs`. If it cannot be found, report the error and **STOP** without changing metadata.
+5. Ensure core is built, then run the bundled helper with parameterized arguments:
-6. Get changed files:
```bash
- git diff "<lastCommitHash>..HEAD" --name-only
+ node "$PLUGIN_ROOT/skills/understand/prepare-incremental.mjs" \
+ "$PROJECT_ROOT" \
+ "$LAST_COMMIT_HASH"
```
- If no files changed: update `meta.json` with the new commit hash and **STOP**.
-
-7. Before filtering by extension, remove every path under the selected `$UA_DIR` from the changed-file list. The selected data directory (`.ua/` or legacy `.understand-anything/`) contains generated graph artefacts, not project source changes. Do **not** update `meta.json` merely because files in this directory changed. If no paths remain after removing `$UA_DIR`, report "Only generated graph artefacts changed. The graph baseline remains associated with the analysed source commit." and **STOP** without writing `meta.json`.
-
-8. Filter the remaining paths to source files only (`.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.rb`, `.cpp`, `.c`, `.h`, `.cs`, `.swift`, `.kt`, `.php`).
- If no source files changed: update `meta.json` with the new commit hash, report "Only non-source files changed. Metadata updated." and **STOP**.
-9. Create intermediate directory:
- ```bash
- mkdir -p "$UA_DIR/intermediate"
- ```
-
-10. **Apply `.understandignore` exclusions** (same semantics as `/understand` Step 2.5 in `agents/project-scanner.md`).
-
- Without this step, files in user-excluded paths (migrations, vendored code, tests) are counted as structural changes and can spuriously escalate the action to `FULL_UPDATE` even when the real change set is tiny.
-
- 1. If neither `$UA_DIR/.understandignore` nor `$PROJECT_ROOT/.understandignore` exists, the step 7 extension filter is sufficient — skip to Phase 1.
-
- 2. Write the step 7 file list to `$UA_DIR/intermediate/changed-files-pre.json` as a JSON array of relative paths.
-
- 3. Resolve `$PLUGIN_ROOT`:
- - Use `$CLAUDE_PLUGIN_ROOT` if set (Claude Code's hook context sets this).
- - Otherwise try `$HOME/.understand-anything-plugin`.
- - Validate the chosen candidate by checking `$candidate/packages/core/dist/ignore-filter.js` exists.
- - If neither resolves: report "Cannot locate plugin install at `$CLAUDE_PLUGIN_ROOT` or `$HOME/.understand-anything-plugin`; auto-update aborted. Run `/understand` to re-baseline." and **STOP**. Do **not** silently skip — silent skip reproduces issue #153.
-
- 4. Write `$UA_DIR/intermediate/ignore-filter.mjs`:
- ```javascript
- import { readFileSync, writeFileSync, existsSync } from 'node:fs';
- import { pathToFileURL } from 'node:url';
- import path from 'node:path';
-
- const PROJECT_ROOT = process.cwd();
- // Data directory: legacy `.understand-anything/` when present, else new `.ua/`.
- const UA_DIR = existsSync(path.join(PROJECT_ROOT, '.understand-anything')) ? '.understand-anything' : '.ua';
- const PLUGIN_ROOT = process.argv[2];
- const inputPath = process.argv[3];
-
- const modUrl = pathToFileURL(
- path.join(PLUGIN_ROOT, 'packages/core/dist/ignore-filter.js'),
- ).href;
- const { createIgnoreFilter } = await import(modUrl);
- const filter = createIgnoreFilter(PROJECT_ROOT);
-
- const input = JSON.parse(readFileSync(inputPath, 'utf-8'));
- const kept = input.filter((p) => !filter.isIgnored(p));
- const removed = input.length - kept.length;
-
- writeFileSync(
- path.join(PROJECT_ROOT, UA_DIR, 'intermediate/changed-files.json'),
- JSON.stringify({ kept, removed, total: input.length }, null, 2),
- );
- console.log(`.understandignore: kept ${kept.length}/${input.length} (removed ${removed})`);
- ```
-
- 5. Run it:
- ```bash
- node "$UA_DIR/intermediate/ignore-filter.mjs" \
- "$PLUGIN_ROOT" \
- "$UA_DIR/intermediate/changed-files-pre.json"
- ```
-
- 6. Read `$UA_DIR/intermediate/changed-files.json`. Pass the `kept` array as the input file list for Phase 1's fingerprint-check script.
-
- 7. If `kept.length === 0`: update `meta.json` with the new commit hash, report "All changed source files are in ignored paths. Metadata updated." and **STOP**.
-
----
-
-## Phase 1 — Structural Fingerprint Check (Zero LLM Tokens)
-
-This phase runs a deterministic Node.js script that compares file structures against stored fingerprints. It costs **zero LLM tokens** — only the script execution cost.
-
-1. Write and execute a Node.js script (`$UA_DIR/intermediate/fingerprint-check.mjs`):
-
-```javascript
-// The script should:
-// 1. Read fingerprints.json from the data directory (.ua/fingerprints.json, or .understand-anything/fingerprints.json when that legacy directory is present — resolve UA_DIR the same way as the other scripts)
-// 2. For each changed source file:
-// a. Read the file content
-// b. Compute SHA-256 content hash
-// c. If content hash matches stored hash → NONE (skip)
-// d. Extract structural elements via regex:
-// - Functions: match patterns like `function NAME(`, `const NAME = (`, `export function NAME(`
-// - Classes: match `class NAME`, `export class NAME`
-// - Imports: match `import ... from '...'`, `import '...'`
-// - Exports: match `export { ... }`, `export default`, `export function`, `export class`, `export const`
-// e. Compare extracted elements against stored fingerprint
-// f. Classify as NONE, COSMETIC, or STRUCTURAL
-// 3. For new files (not in fingerprints.json): classify as STRUCTURAL
-// 4. For deleted files (in fingerprints.json but not on disk): classify as STRUCTURAL
-// 5. Determine overall decision:
-// - All NONE/COSMETIC → action: "SKIP"
-// - Some STRUCTURAL, ≤10 files, same directories → action: "PARTIAL_UPDATE"
-// - New/deleted directories or >10 structural files → action: "ARCHITECTURE_UPDATE"
-// - >30 structural files or >50% of graph → action: "FULL_UPDATE"
-// 6. Write result to <UA_DIR>/intermediate/change-analysis.json (.ua/, or .understand-anything/ when that legacy directory is present)
-```
+ The helper is authoritative for `git diff --name-status -z`, renames, spaces, POSIX normalization, the current scan/ignore rules, structural fingerprints, generated artifacts, and selective import-map refresh. Do not recreate or post-filter its decisions.
+6. Read `$UA_DIR/intermediate/incremental-plan.json`.
-The output JSON should have this shape:
-```json
-{
- "action": "SKIP | PARTIAL_UPDATE | ARCHITECTURE_UPDATE | FULL_UPDATE",
- "filesToReanalyze": ["src/new-feature.ts"],
- "rerunArchitecture": false,
- "rerunTour": false,
- "reason": "1 file has structural changes (new function added)",
- "fileChanges": [
- { "filePath": "src/utils.ts", "changeLevel": "COSMETIC", "details": ["internal logic changed"] },
- { "filePath": "src/new-feature.ts", "changeLevel": "STRUCTURAL", "details": ["new function: handleRequest"] }
- ]
-}
-```
-
-2. Read `$UA_DIR/intermediate/change-analysis.json`.
-
-3. **Decision gate:**
-
- | Action | What to do |
+ | Action | Required behavior |
|---|---|
- | `SKIP` | Update `meta.json` with new commit hash. Report: "No structural changes detected. Graph metadata updated. Zero tokens spent." **STOP.** |
- | `FULL_UPDATE` | Report: "Major structural changes detected (reason). Recommend running `/understand --full` for a complete rebuild." **STOP.** |
- | `PARTIAL_UPDATE` | Proceed to Phase 2 with `filesToReanalyze` |
- | `ARCHITECTURE_UPDATE` | Proceed to Phase 2 with `filesToReanalyze`, flag architecture re-run |
-
----
-
-## Phase 2 — Targeted Re-Analysis (Minimal Token Cost)
-
-Only re-analyze files with structural changes. This is the **only** phase that costs LLM tokens.
-
-1. Read the existing knowledge graph from `$UA_DIR/knowledge-graph.json`.
+ | `SKIP` | Run the finalizer below. It advances scan/fingerprint/meta for safe cosmetic or irrelevant changes and intentionally advances nothing for generated-only commits. Report zero tokens spent and **STOP**. |
+ | `PARTIAL_UPDATE` | Continue with targeted analysis. |
+ | `ARCHITECTURE_UPDATE` | Continue with targeted analysis, then rerun architecture and tour. |
+ | `FULL_UPDATE` | Immediately invoke `/understand --full`; do not patch the incremental baseline. |
-2. Batch the files from `filesToReanalyze` (from Phase 1). Use a single batch if ≤10 files, otherwise batch into groups of 5-10.
+ SKIP finalizer:
-3. For each batch, dispatch a subagent using the `file-analyzer` agent definition (at `agents/file-analyzer.md`). Append:
-
- > **Additional context from main session:**
- >
- > Project: `<projectName from existing graph>` — `<projectDescription>`
- > Frameworks detected: `<frameworks from existing graph>`
- > Languages: `<languages from existing graph>`
- >
- > **IMPORTANT:** This is an incremental update. Only the files listed below have structural changes. Analyze them thoroughly but do not invent nodes for files not in this batch.
-
- Fill in batch-specific parameters:
-
- > Analyze these source files and produce GraphNode and GraphEdge objects.
- > Project root: `$PROJECT_ROOT`
- > Project: `<projectName>`
- > Languages: `<languages>`
- > Batch index: `1`
- > Write output to: `$UA_DIR/intermediate/batch-1.json`
- >
- > All project files (for import resolution):
- > `<file list from existing graph nodes>`
- >
- > Files to analyze in this batch:
- > 1. `<path>` (`<sizeLines>` lines)
- > ...
-
-4. After batch(es) complete, read each `batch-<N>.json` and merge results.
-
-5. **Merge with existing graph:**
- - Remove old nodes whose `filePath` matches any file in `filesToReanalyze` or in the deleted files list
- - Remove old edges whose `source` or `target` references a removed node
- - Add new nodes and edges from the fresh analysis
- - Deduplicate nodes by ID (keep latest), edges by `source + target + type`
- - Remove any edge with dangling `source` or `target` references
-
----
-
-## Phase 3 — Conditional Architecture/Tour + Save
-
-### 3a. Architecture update (only if `rerunArchitecture === true`)
-
-If the change analysis flagged `ARCHITECTURE_UPDATE`:
+ ```bash
+ node "$PLUGIN_ROOT/skills/understand/finalize-incremental.mjs" "$PROJECT_ROOT"
+ ```
-1. Dispatch a subagent using the `architecture-analyzer` agent definition (at `agents/architecture-analyzer.md`), passing the full merged node set and import edges. Include previous layer definitions for naming consistency:
+## Phase 1 — Targeted file analysis
- > Previous layer definitions (for naming consistency):
- > ```json
- > [previous layers from existing graph]
- > ```
- > Maintain the same layer names and IDs where possible. Only add/remove layers if the file structure has materially changed.
+Read `filesToReanalyze` from the plan. It never contains deleted, ignored, cosmetic, or generated-artifact paths.
-2. After completion, read and normalize layers (same normalization as `/understand` Phase 4).
+- If the list is empty, dispatch no agent and create no new batch file. Continue directly to merge; `batch-existing.json` already contains the pruned graph. This covers deletion-only updates at zero token cost.
+- Otherwise compute only changed batches:
-3. Optionally re-run tour builder if layers changed significantly.
+ ```bash
+ node "$PLUGIN_ROOT/skills/understand/compute-batches.mjs" "$PROJECT_ROOT" \
+ --changed-files="$UA_DIR/intermediate/changed-files.txt"
+ ```
-### 3b. Lite layer update (if `rerunArchitecture === false`)
+ Dispatch file-analyzer for those batches only, using `agents/file-analyzer.md` and the batch prompt contract from the `/understand` skill. Preserve each original batch index in its output filename. Retry a failed dispatch once; if it still fails, **STOP** without running the finalizer or advancing the baseline.
-If only a partial update:
-1. For **new files**: assign them to the most likely existing layer based on directory path matching
-2. For **deleted files**: remove their IDs from layer `nodeIds` arrays
-3. Remove any layer that ends up with zero nodeIds
+## Phase 2 — Merge
-### 3c. Lite validation
+Run the deterministic merge in both empty and non-empty analyzer cases:
-Perform lightweight validation (no graph-reviewer agent):
-1. Remove any edge with dangling `source` or `target`
-2. Remove any layer `nodeIds` entry that doesn't exist in the node set
-3. Ensure every file node appears in exactly one layer (add to a catch-all layer if missing)
+```bash
+python "$PLUGIN_ROOT/skills/understand/merge-batch-graphs.py" "$PROJECT_ROOT"
+```
-### 3d. Save
+It combines `batch-existing.json` with fresh batches and recovers imports from the refreshed `scan-result.json`, including `config:`, `schema:`, `service:`, and other valid whole-file nodes. Require `$UA_DIR/intermediate/assembled-graph.json`; on failure, report it and **STOP** without advancing fingerprints or meta.
-1. Write the final knowledge graph to `$UA_DIR/knowledge-graph.json`.
+Do not dispatch assemble-reviewer or graph-reviewer for automatic updates.
-2. Write updated metadata to `$UA_DIR/meta.json`:
- ```json
- {
- "lastAnalyzedAt": "<ISO 8601 timestamp>",
- "gitCommitHash": "<current commit hash>",
- "version": "1.0.0",
- "analyzedFiles": <total file count in graph>
- }
- ```
+## Phase 3 — Conditional architecture and tour
-3. **Update fingerprints (LOAD-PATCH-SAVE, not OVERWRITE).**
-
- The most common failure mode here: writing only the freshly-computed batch entries to `fingerprints.json`, discarding every other file's fingerprint. The next auto-update then sees all those files as new (no stored fingerprint), classifies them as STRUCTURAL, and escalates to FULL_UPDATE permanently (issue #152). The script must LOAD ALL existing entries, PATCH only the re-analyzed ones, and SAVE the full dict back.
-
- Write and execute a Node.js script in this exact ordering:
-
- ```javascript
- import { readFileSync, writeFileSync, existsSync } from 'node:fs';
- import { createHash } from 'node:crypto';
- import path from 'node:path';
-
- const UA_DIR = existsSync(path.join(PROJECT_ROOT, '.understand-anything')) ? '.understand-anything' : '.ua';
- const fpPath = path.join(PROJECT_ROOT, UA_DIR, 'fingerprints.json');
- const existedAndNonEmpty = existsSync(fpPath) && readFileSync(fpPath, 'utf-8').trim().length > 0;
-
- // 1. LOAD ALL existing entries (NEVER skip — preserves un-analyzed files)
- const all = existedAndNonEmpty
- ? JSON.parse(readFileSync(fpPath, 'utf-8'))
- : {};
- const before = Object.keys(all).length;
-
- // 2. PATCH (file still exists) or REMOVE (file deleted) for each re-analyzed path.
- // `filesToReanalyze` may include paths that were deleted in this commit —
- // handle both branches inline rather than expecting a separate deleted list.
- for (const filePath of filesToReanalyze) {
- const fullPath = path.join(PROJECT_ROOT, filePath);
- if (!existsSync(fullPath)) {
- delete all[filePath];
- continue;
- }
- const content = readFileSync(fullPath, 'utf-8');
- const contentHash = createHash('sha256').update(content).digest('hex');
- // Extract functions, classes, imports, exports via the same regex as Phase 1.
- all[filePath] = { contentHash, functions, classes, imports, exports };
- }
-
- // 3. GUARD against silent load failure: if fingerprints.json existed and was
- // non-empty but `before` came out as 0, refuse to overwrite — something
- // went wrong reading the file and writing now would clobber every entry.
- if (existedAndNonEmpty && before === 0) {
- throw new Error('fingerprints.json existed and was non-empty but loaded as {} — refusing to overwrite');
- }
-
- // 4. SAVE ALL entries back (full dict — not just the patched subset)
- writeFileSync(fpPath, JSON.stringify(all, null, 2));
- console.log(`Fingerprints: ${before} → ${Object.keys(all).length}`);
- ```
+- For `PARTIAL_UPDATE`, dispatch neither agent. The finalizer preserves existing layer assignments and tour prose, removes dangling references/empty layers, and assigns new nodes deterministically by directory depth, graph connectivity, then prior layer order.
+- For `ARCHITECTURE_UPDATE`, dispatch architecture-analyzer on the full merged node/edge set, including previous layers for naming stability, and write `$UA_DIR/intermediate/layers.json`. Then dispatch tour-builder and write `$UA_DIR/intermediate/tour.json`.
- The `existedAndNonEmpty && before === 0` guard catches the silent-load-failure case before it corrupts the store. If the count shrinks from N to a small number that matches the batch size, the LOAD step was skipped — abort the write rather than persist the wrong dict.
+Retry either required agent once. If it still fails, **STOP** without advancing the baseline.
-4. Clean up intermediate files:
- ```bash
- INTERMEDIATE_DIR="$UA_DIR/intermediate"
- if [ -n "$PROJECT_ROOT" ] && [ -d "$INTERMEDIATE_DIR" ]; then
- rm -rf "$INTERMEDIATE_DIR"
- fi
- ```
+## Phase 4 — Atomic save and baseline patch
-5. Report a summary:
- - Files checked: N (total changed)
- - Structural changes found: N files
- - Cosmetic-only changes: N files (skipped)
- - Nodes updated: N
- - Action taken: PARTIAL_UPDATE / ARCHITECTURE_UPDATE
- - Path to output: `$UA_DIR/knowledge-graph.json`
+Run:
----
+```bash
+node "$PLUGIN_ROOT/skills/understand/finalize-incremental.mjs" "$PROJECT_ROOT"
+```
-## Error Handling
+The finalizer performs deterministic graph/layer/tour validation, atomically saves `knowledge-graph.json`, patches changed fingerprints while preserving untouched entries, removes deleted fingerprints, and only then writes `meta.json`. A graph-save failure must never advance the fingerprint or commit baseline.
-- If the fingerprint check script fails: fall back to treating all changed files as STRUCTURAL (conservative approach).
-- If `fingerprints.json` doesn't exist: treat all changed files as STRUCTURAL and regenerate fingerprints after the update.
-- If a subagent dispatch fails: retry once. If it fails again, save partial results and report the error.
-- ALWAYS save partial results — a partially updated graph is better than no update.
+Report:
----
+- action taken;
+- files structurally analyzed;
+- deleted/ignored/cosmetic/generated counts from the plan;
+- whether architecture/tour ran;
+- output path.
-## Notes
+## Error handling
-- This skill reuses the same `file-analyzer` and `architecture-analyzer` agent definitions as `/understand` — no separate agent prompts needed.
-- The fingerprint comparison in Phase 1 uses regex-based extraction (not tree-sitter) because it runs as a temporary Node.js script and doesn't need full AST accuracy — just signature-level detection.
-- The authoritative fingerprints stored in `fingerprints.json` are generated by `/understand` Phase 7 using the core `fingerprint.ts` module (which uses tree-sitter for precise extraction).
+- Never fall back to a hand-written regex fingerprint script or an extension-only changed-file filter.
+- Never pass a deleted or ignored path to file-analyzer.
+- Never update `meta.json` after a failed graph/agent phase.
+- Never update `meta.json` for a generated-artifact-only commit.
+- Surface every warning or failure; a subsequent run can safely retry because the helper reconstructs the previous inventory from scan results, graph node `filePath` values, and fingerprints.
diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md
index f13012e0..b8f271fa 100644
--- a/understand-anything-plugin/skills/understand/SKILL.md
+++ b/understand-anything-plugin/skills/understand/SKILL.md
@@ -168,7 +168,7 @@ Determine whether to run a full analysis or incremental update.
- Split on commas, trim whitespace from each pattern, and filter out empty entries.
- Store the patterns as `$EXCLUDE_PATTERNS` (comma-joined for passing to downstream scripts: `"tests/*,docs/*"`).
- These patterns take highest priority — they are applied on top of default patterns and `.understandignore` rules. Use `!` prefix to force-include files that would otherwise be excluded.
- - **Note:** Newly added `--exclude` patterns require a `--full` scan to take effect.
+ - Incremental preparation re-scans the current inventory, so newly supplied exclusions take effect immediately and remove any previously analyzed files they now cover.
4. **Check for subdomain knowledge graphs to merge:**
List all `*knowledge-graph*.json` files in `$UA_DIR/` **excluding** `knowledge-graph.json` itself (e.g. `frontend-knowledge-graph.json`, `backend-knowledge-graph.json`). If any subdomain graphs exist, run the merge script bundled with this skill (located next to this SKILL.md file — use the skill directory path, not the project root):
@@ -178,7 +178,7 @@ Determine whether to run a full analysis or incremental update.
The script discovers subdomain graphs, loads the existing `knowledge-graph.json` as a base (if present), and merges everything into `knowledge-graph.json` (deduplicating nodes and edges). Report the merge summary to the user, then continue with the merged graph.
5. Check if `$UA_DIR/knowledge-graph.json` exists. If it does, read it.
-6. Check if `$UA_DIR/meta.json` exists. If it does, read it to get `gitCommitHash`.
+6. Check if `$UA_DIR/meta.json` exists. If it does, read its `gitCommitHash` and store it as `$LAST_COMMIT_HASH`.
7. **Decision logic:**
| Condition | Action |
@@ -187,15 +187,41 @@ Determine whether to run a full analysis or incremental update.
| No existing graph or meta | Full analysis (all phases) |
| `--review` flag + existing graph + unchanged commit hash | Skip to Phase 6 (review-only — reuse existing assembled graph) |
| Existing graph + unchanged commit hash | Ask the user: "The graph is up to date at this commit. Would you like to: **(a)** run a full rebuild (`--full`), **(b)** run the LLM graph reviewer (`--review`), or **(c)** do nothing?" Then follow their choice. If they pick (c), STOP. |
- | Existing graph + changed files | Incremental update (re-analyze changed files only) |
+ | Existing graph + changed files | Run deterministic incremental preparation below |
**Review-only path:** Copy the existing `knowledge-graph.json` to `$UA_DIR/intermediate/assembled-graph.json`, then jump directly to Phase 6 step 3.
- For incremental updates, get the changed file list:
+ For incremental updates, do **not** construct the changed-file list by hand. Run the bundled reconciliation helper with the previous analyzed commit. Pass `--exclude "$EXCLUDE_PATTERNS"` only when the option is non-empty:
```bash
- git diff <lastCommitHash>..HEAD --name-only
+ node "<SKILL_DIR>/prepare-incremental.mjs" \
+ "$PROJECT_ROOT" \
+ "$LAST_COMMIT_HASH"
```
- If this returns no files, report "Graph is up to date" and STOP.
+
+ With explicit exclusions:
+ ```bash
+ node "<SKILL_DIR>/prepare-incremental.mjs" \
+ "$PROJECT_ROOT" \
+ "$LAST_COMMIT_HASH" \
+ --exclude "$EXCLUDE_PATTERNS"
+ ```
+
+ The helper uses parameterized `git diff --name-status -z`, performs a fresh deterministic scan with the current `.understandignore` / `--exclude` rules, compares structural fingerprints, selectively refreshes imports, and atomically writes:
+ - `$UA_DIR/intermediate/incremental-plan.json`
+ - `$UA_DIR/intermediate/scan-result.json`
+ - `$UA_DIR/intermediate/changed-files.txt`
+ - `$UA_DIR/intermediate/batch-existing.json` for partial/architecture updates
+
+ Read `incremental-plan.json` and store its `action`, `filesToReanalyze`, `deletedFiles`, `rerunArchitecture`, and `rerunTour` values. Follow this gate:
+
+ | Prepared action | Next step |
+ |---|---|
+ | `SKIP` | Run `node "<SKILL_DIR>/finalize-incremental.mjs" "$PROJECT_ROOT"`. It updates scan/fingerprints/meta for cosmetic or irrelevant changes, but intentionally advances nothing for generated-artifact-only commits. Report zero LLM tokens spent and **STOP**. |
+ | `PARTIAL_UPDATE` | Skip Phase 0.5 and Phase 1; continue with the incremental Phase 1.5/2 path. |
+ | `ARCHITECTURE_UPDATE` | Skip Phase 0.5 and Phase 1; continue with incremental analysis, then rerun Phase 4 and Phase 5. |
+ | `FULL_UPDATE` | Switch to the existing full pipeline beginning at Phase 0.5. Do not patch fingerprints or metadata from the incremental helper. |
+
+ `filesToReanalyze` contains only current, non-ignored files with structural changes. Deletions, newly ignored files, cosmetic changes, and generated artifacts are never passed to file-analyzer.
8. **Collect project context for subagent injection:**
- Read `README.md` (or `README.rst`, `readme.md`) from `$PROJECT_ROOT` if it exists. Store as `$README_CONTENT` (first 3000 characters).
@@ -209,9 +235,9 @@ Determine whether to run a full analysis or incremental update.
---
-## Phase 0.5 — Ignore Configuration
+## Phase 0.5 — Ignore Configuration (full analysis only)
-Set up and verify the `.understandignore` file before scanning.
+Set up and verify the `.understandignore` file before a full scan. Incremental preparation already applies the current ignore rules and must skip this confirmation phase.
1. Check if `$UA_DIR/.understandignore` exists.
2. **If it does NOT exist**, generate a starter file by invoking the bundled script (delegates to `generateStarterIgnoreFile` in `@understand-anything/core`, which reads `.gitignore`, deduplicates against built-in defaults, and emits language-grouped test-file suggestions). Pass `$PLUGIN_ROOT` via the env so the script doesn't have to re-derive it from its own path (which breaks for copied skill installs):
@@ -279,12 +305,22 @@ If the scan result includes `filteredByIgnore > 0`, report:
Report: `[Phase 1.5/7] Computing semantic batches...`
-Run the bundled batching script:
+For a full analysis, run the bundled batching script:
```bash
node "<SKILL_DIR>/compute-batches.mjs" "$PROJECT_ROOT"
```
-Reads `$UA_DIR/intermediate/scan-result.json`, writes `$UA_DIR/intermediate/batches.json`.
+For `PARTIAL_UPDATE` or `ARCHITECTURE_UPDATE`, inspect `filesToReanalyze` from the prepared plan:
+
+- If it is empty, skip batching and file-analyzer entirely. `batch-existing.json` already contains the deletion/ignore cleanup baseline; continue to the merge step in Phase 2. This is the zero-token deletion path.
+- Otherwise run batching against the helper-produced file, which contains only structurally changed current files:
+
+ ```bash
+ node "<SKILL_DIR>/compute-batches.mjs" "$PROJECT_ROOT" \
+ --changed-files="$UA_DIR/intermediate/changed-files.txt"
+ ```
+
+Both forms read the freshly reconciled `$UA_DIR/intermediate/scan-result.json` and write `$UA_DIR/intermediate/batches.json`.
Capture stderr. Append any line starting with `Warning:` to `$PHASE_WARNINGS` for the final report.
@@ -360,34 +396,24 @@ Include the script's warnings in `$PHASE_WARNINGS` for the reviewer.
### Incremental update path
-Write the changed-files list (one path per line) to a temp file:
-```bash
-git diff "<lastCommitHash>..HEAD" --name-only > "$UA_DIR/tmp/changed-files.txt"
-```
+`prepare-incremental.mjs` has already refreshed the complete file inventory and `importMap`, written the exact analyzer list, and pruned changed/deleted paths from the old graph into `batch-existing.json`.
-Run compute-batches with `--changed-files`:
-```bash
-node "<SKILL_DIR>/compute-batches.mjs" "$PROJECT_ROOT" \
- --changed-files="$UA_DIR/tmp/changed-files.txt"
-```
+1. If `filesToReanalyze` is non-empty, dispatch file-analyzer only for the batches from the incremental `batches.json`, using the same prompt template as the full path. Never add `deletedFiles`, `cosmeticFiles`, `ignoredFiles`, or `generatedArtifactFiles` to a prompt.
+2. If `filesToReanalyze` is empty, dispatch no agent and create no new batch file.
+3. Run the merge script in both cases:
-This produces a `batches.json` that contains only batches with changed files, but neighborMap entries still reference unchanged files (with their full-graph batchIndex) so cross-batch edges remain emittable.
-
-Then dispatch file-analyzer subagents per the same template as the full path.
-
-After batches complete:
-1. Remove old nodes whose `filePath` matches any changed file from the existing graph
-2. Remove old edges whose `source` or `target` references a removed node
-3. Write the pruned existing nodes/edges as `batch-existing.json` in the intermediate directory
-4. Run the same merge script — it will combine `batch-existing.json` with the fresh `batch-*.json` files:
```bash
python "<SKILL_DIR>/merge-batch-graphs.py" "$PROJECT_ROOT"
```
+The merge combines `batch-existing.json` with any fresh batch output. Its import recovery reads the already-refreshed `scan-result.json`, so added and removed imports are reflected during this same run. Verify `assembled-graph.json` exists before continuing.
+
---
## Phase 3 — ASSEMBLE REVIEW
+Run this phase for **full analysis only**. Both incremental actions skip assemble-reviewer: their deterministic merge/reconciliation checks replace this whole-graph LLM pass. The user-facing `--review` option is still honored later by the graph-reviewer in Phase 6.
+
Report to the user: `[Phase 3/7] Reviewing assembled graph...`
Dispatch a subagent using the `assemble-reviewer` agent definition (at `agents/assemble-reviewer.md`).
@@ -415,6 +441,8 @@ After the subagent completes, read `$UA_DIR/intermediate/assemble-review.json` a
## Phase 4 — ARCHITECTURE
+Run this phase for full analysis and for incremental plans where `rerunArchitecture === true`. For `PARTIAL_UPDATE`, dispatch no architecture agent; `finalize-incremental.mjs` preserves surviving assignments, removes dangling/empty layers, and assigns new nodes deterministically by deepest common parent directory, then graph connectivity, then previous layer order.
+
Report to the user: `[Phase 4/7] Identifying architectural layers...`
**Build the combined prompt template:**
@@ -483,7 +511,7 @@ Each element of the final `layers` array MUST have this shape:
All four fields (`id`, `name`, `description`, `nodeIds`) are required.
-**For incremental updates:** Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change.
+**For architecture incremental updates:** Re-run architecture analysis on the full merged node set. Ordinary partial updates use the deterministic placement described at the start of this phase.
**Context for incremental updates:** When re-running architecture analysis, also inject the previous layer definitions:
@@ -498,6 +526,8 @@ All four fields (`id`, `name`, `description`, `nodeIds`) are required.
## Phase 5 — TOUR
+Run this phase for full analysis and for incremental plans where `rerunTour === true`. For `PARTIAL_UPDATE`, dispatch no tour agent and do not rewrite the narrative; finalization only removes dangling node IDs from the existing steps.
+
Report to the user: `[Phase 5/7] Building guided tour...`
Dispatch a subagent using the `tour-builder` agent definition (at `agents/tour-builder.md`). Append the following additional context:
@@ -567,12 +597,27 @@ Each element of the final `tour` array MUST have this shape:
Required fields: `order`, `title`, `description`, `nodeIds`. Preserve optional `languageLesson` when present.
+### Incremental deterministic save gate
+
+After the applicable Phase 4/5 work is complete, finalize either incremental action:
+
+```bash
+node "<SKILL_DIR>/finalize-incremental.mjs" "$PROJECT_ROOT"
+```
+
+This helper validates/deduplicates nodes and edges, reconciles layers/tour, atomically saves the graph, patches only changed fingerprints while preserving all others, removes deleted fingerprints, and only then advances `meta.json`.
+
+- Without `--review`, report the incremental summary and **STOP**. Do not run Phase 6 or the full-save Phase 7; this is what prevents the ordinary local update from paying for whole-graph review.
+- With `--review`, copy the newly saved `$UA_DIR/knowledge-graph.json` to `$UA_DIR/intermediate/assembled-graph.json`, then continue to the full graph-reviewer path in Phase 6. Do not run the inline default reviewer.
+
---
## Phase 6 — REVIEW
Report to the user: `[Phase 6/7] Validating knowledge graph...`
+For incremental `--review`, the save gate already copied a complete KnowledgeGraph to `assembled-graph.json`. Do not reconstruct it from node/edge-only merge output; skip directly to the `--review` graph-reviewer path below. The default inline path is for full analysis only.
+
Assemble the full KnowledgeGraph JSON object:
```json
@@ -747,7 +792,7 @@ Report to the user: `[Phase 7/7] Saving knowledge graph...`
const outputPath = process.argv[3];
const input = {
projectRoot,
- sourceFilePaths: [<all source file paths from Phase 1, as JSON array>],
+ filePaths: [<all analyzed file paths from Phase 1, including non-code files, as JSON array>],
gitCommitHash: "<current commit hash>",
};
fs.writeFileSync(outputPath, JSON.stringify(input, null, 2));
@@ -760,7 +805,7 @@ Report to the user: `[Phase 7/7] Saving knowledge graph...`
"$UA_DIR/intermediate/fingerprint-input.json"
```
- The script uses `TreeSitterPlugin + PluginRegistry` exactly like `extract-structure.mjs`, so the baseline matches the comparison logic used during auto-updates.
+ The script uses `TreeSitterPlugin + PluginRegistry` exactly like `extract-structure.mjs`, so the baseline matches incremental comparison. The baseline MUST include every file in `scan-result.json`, not only source-code files; unsupported formats receive conservative content-only fingerprints.
**If the script exits non-zero or stdout does not include `Fingerprints baseline:`, abort Phase 7 and report the error. Do NOT proceed to step 3 (writing `meta.json`).**