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.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
perf(understand): gate LLM graph-reviewer behind --review flag, add inline deterministic validation
Lum11042d86d339c048
diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.mdindex 71f188ff..13cabcde 100644--- a/understand-anything-plugin/skills/understand/SKILL.md+++ b/understand-anything-plugin/skills/understand/SKILL.md@@ -12,6 +12,7 @@ Analyze the current codebase and produce a `knowledge-graph.json` file in `.unde- `$ARGUMENTS` may contain:- `--full` — Force a full rebuild, ignoring any existing graph+ - `--review` — Run full LLM graph-reviewer instead of inline deterministic validation- A directory path — Scope analysis to a specific subdirectory---@@ -327,7 +328,93 @@ Assemble the full KnowledgeGraph JSON object:2. Write the assembled graph to `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`.-3. Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context:+3. **Check `$ARGUMENTS` for `--review` flag.** Then run the appropriate validation path:++---++#### Default path (no `--review`): inline deterministic validation++Write the following Node.js script to `$PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs`:++```javascript+#!/usr/bin/env node+const fs = require('fs');+const graphPath = process.argv[2];+const outputPath = process.argv[3];+try {+ const graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));+ const issues = [], warnings = [];+ if (!Array.isArray(graph.nodes)) { issues.push('graph.nodes is missing or not an array'); graph.nodes = []; }+ if (!Array.isArray(graph.edges)) { issues.push('graph.edges is missing or not an array'); graph.edges = []; }+ const nodeIds = new Set();+ const seen = new Map();+ graph.nodes.forEach((n, i) => {+ if (!n.id) { issues.push(`Node[${i}] missing id`); return; }+ if (!n.type) issues.push(`Node[${i}] '${n.id}' missing type`);+ if (!n.name) issues.push(`Node[${i}] '${n.id}' missing name`);+ if (!n.summary) issues.push(`Node[${i}] '${n.id}' missing summary`);+ if (!n.tags || !n.tags.length) issues.push(`Node[${i}] '${n.id}' missing tags`);+ if (seen.has(n.id)) issues.push(`Duplicate node ID '${n.id}' at indices ${seen.get(n.id)} and ${i}`);+ else seen.set(n.id, i);+ nodeIds.add(n.id);+ });+ graph.edges.forEach((e, i) => {+ if (!nodeIds.has(e.source)) issues.push(`Edge[${i}] source '${e.source}' not found`);+ if (!nodeIds.has(e.target)) issues.push(`Edge[${i}] target '${e.target}' not found`);+ });+ const fileNodes = graph.nodes.filter(n => n.type === 'file').map(n => n.id);+ const assigned = new Map();+ (graph.layers || []).forEach(layer => {+ (layer.nodeIds || []).forEach(id => {+ if (!nodeIds.has(id)) issues.push(`Layer '${layer.id}' refs missing node '${id}'`);+ if (assigned.has(id)) issues.push(`Node '${id}' appears in multiple layers`);+ assigned.set(id, layer.id);+ });+ });+ fileNodes.forEach(id => {+ if (!assigned.has(id)) issues.push(`File node '${id}' not in any layer`);+ });+ (graph.tour || []).forEach((step, i) => {+ (step.nodeIds || []).forEach(id => {+ if (!nodeIds.has(id)) issues.push(`Tour step[${i}] refs missing node '${id}'`);+ });+ });+ const withEdges = new Set([+ ...graph.edges.map(e => e.source),+ ...graph.edges.map(e => e.target)+ ]);+ graph.nodes.forEach(n => {+ if (!withEdges.has(n.id)) warnings.push(`Node '${n.id}' has no edges (orphan)`);+ });+ const stats = {+ totalNodes: graph.nodes.length,+ totalEdges: graph.edges.length,+ totalLayers: (graph.layers || []).length,+ tourSteps: (graph.tour || []).length,+ nodeTypes: graph.nodes.reduce((a, n) => { a[n.type] = (a[n.type]||0)+1; return a; }, {}),+ edgeTypes: graph.edges.reduce((a, e) => { a[e.type] = (a[e.type]||0)+1; return a; }, {})+ };+ fs.writeFileSync(outputPath, JSON.stringify({ issues, warnings, stats }, null, 2));+ process.exit(0);+} catch (err) { process.stderr.write(err.message + '\n'); process.exit(1); }+```++Execute it:+```bash+node $PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs \+ "$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json" \+ "$PROJECT_ROOT/.understand-anything/intermediate/review.json"+```++If the script exits non-zero, read stderr, fix the script, and retry once.++---++#### `--review` path: full LLM reviewer++If `--review` IS in `$ARGUMENTS`, dispatch the LLM graph-reviewer subagent as follows:++Dispatch a subagent using the prompt template at `./graph-reviewer-prompt.md`. Read the template file and pass the full content as the subagent's prompt, appending the following additional context:> **Additional context from main session:**>@@ -343,14 +430,16 @@ Assemble the full KnowledgeGraph JSON object:Pass these parameters in the dispatch prompt:- > Validate the knowledge graph at `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`.- > Project root: `$PROJECT_ROOT`- > Read the file and validate it for completeness and correctness.- > Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/review.json`+> Validate the knowledge graph at `$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json`.+> Project root: `$PROJECT_ROOT`+> Read the file and validate it for completeness and correctness.+> Write output to: `$PROJECT_ROOT/.understand-anything/intermediate/review.json`++----4. After the subagent completes, read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`.+4. Read `$PROJECT_ROOT/.understand-anything/intermediate/review.json`.-5. **If `approved: false`:**+5. **If `issues` array is non-empty:**- Review the `issues` list- Apply automated fixes where possible:- Remove edges with dangling references@@ -359,7 +448,7 @@ Pass these parameters in the dispatch prompt:- Re-run the final graph validation after automated fixes- If critical issues remain after one fix attempt, save the graph anyway but include the warnings in the final report and mark dashboard auto-launch as skipped-6. **If `approved: true`:** Proceed to Phase 7.+6. **If `issues` array is empty:** Proceed to Phase 7.---@@ -401,7 +490,7 @@ Pass these parameters in the dispatch prompt:## Error Handling- If any subagent dispatch fails, retry **once** with the same prompt plus additional context about the failure.-- Track all warnings and errors from each phase in a `$PHASE_WARNINGS` list. Pass this list to the graph-reviewer in Phase 6 for comprehensive validation.+- Track all warnings and errors from each phase in a `$PHASE_WARNINGS` list. When using `--review`, pass this list to the graph-reviewer in Phase 6. On the default path, include accumulated warnings in the Phase 7 final report.- If it fails a second time, skip that phase and continue with partial results.- ALWAYS save partial results — a partial graph is better than no graph.- Report any skipped phases or errors in the final summary so the user knows what happened.