/understand

Analyze the current codebase and produce a

knowledge-graph.json

.understand-anything/

Options

• $ARGUMENTS

  may contain:

  • --full

    — Force a full rebuild, ignoring any existing graph
  • A directory path — Scope analysis to a specific subdirectory

Phase 0 — Pre-flight

Determine whether to run a full analysis or incremental update.

1. Set

   PROJECT_ROOT

   to the current working directory.

2. Get the current git commit hash:

   git rev-parse HEAD
   

3. Create the intermediate output directory:

   mkdir -p $PROJECT_ROOT/.understand-anything/intermediate
   

4. Check if

   $PROJECT_ROOT/.understand-anything/knowledge-graph.json

   exists. If it does, read it.

5. Check if

   $PROJECT_ROOT/.understand-anything/meta.json

   exists. If it does, read it to get

   gitCommitHash

   .

6. Decision logic:

   Condition	Action
   --full flag in $ARGUMENTS	Full analysis (all phases)
   No existing graph or meta	Full analysis (all phases)
   Existing graph + unchanged commit hash	Report "Graph is up to date" and STOP
   Existing graph + changed files	Incremental update (re-analyze changed files only)

   For incremental updates, get the changed file list:

   git diff <lastCommitHash>..HEAD --name-only
   

   If this returns no files, report "Graph is up to date" and STOP.

Phase 1 — SCAN (Full analysis only)

Dispatch the project-scanner agent with this prompt:

Scan this project directory to discover all source files, detect languages and frameworks. Project root:

$PROJECT_ROOT

Write output to:

$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json

After the agent completes, read

$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json

• Project name, description
• Languages, frameworks
• File list with line counts
• Complexity estimate

Gate check: If >200 files, inform the user and suggest scoping with a subdirectory argument. Proceed only if user confirms or add guidance that this may take a while.

Phase 2 — ANALYZE

Full analysis path

Batch the file list from Phase 1 into groups of 5-10 files each (aim for balanced batch sizes).

For each batch, dispatch a file-analyzer agent. Run up to 3 agents concurrently using parallel dispatch. Each agent gets this prompt:

Analyze these source files and produce GraphNode and GraphEdge objects. Project root:

$PROJECT_ROOT

Project:

<projectName>

Languages:

<languages>

Batch index:

<batchIndex>

Write output to:

$PROJECT_ROOT/.understand-anything/intermediate/batch-<batchIndex>.json

All project files (for import resolution):

<full file path list from scan>

Files to analyze in this batch:

1. <path>

   (<sizeLines> lines)

2. <path>

   (<sizeLines> lines) ...

After ALL batches complete, read each

batch-<N>.json

• Combine all

  nodes

  arrays. If duplicate node IDs exist, keep the later occurrence.
• Combine all

  edges

  arrays. Deduplicate by the composite key

  source + target + type

  .

Incremental update path

Use the changed files list from Phase 0. Batch and dispatch file-analyzer agents using the same process as above, but only for changed files.

After batches complete, merge with the existing graph:

1. Remove old nodes whose

   filePath

   matches any changed file
2. Remove old edges whose

   source

   or

   target

   references a removed node
3. Add new nodes and edges from the fresh analysis

Phase 3 — ASSEMBLE

Merge all file-analyzer results into a single set of nodes and edges. Then perform basic integrity cleanup:

• Remove any edge whose

  source

  or

  target

  references a node ID that does not exist in the merged node set
• Remove duplicate node IDs (keep the last occurrence)
• Log any removed edges or nodes for the final summary

Phase 4 — ARCHITECTURE

Dispatch the architecture-analyzer agent with this prompt:

Analyze this codebase's structure to identify architectural layers. Project root:

$PROJECT_ROOT

Write output to:

$PROJECT_ROOT/.understand-anything/intermediate/layers.json

Project:

<projectName>

—

<projectDescription>

File nodes:

[list of {id, name, filePath, summary, tags} for all file-type nodes]

Import edges:

[list of edges with type "imports"]

After the agent completes, read

$PROJECT_ROOT/.understand-anything/intermediate/layers.json

For incremental updates: Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change.

Phase 5 — TOUR

Dispatch the tour-builder agent with this prompt:

Create a guided learning tour for this codebase. Project root:

$PROJECT_ROOT

Write output to:

$PROJECT_ROOT/.understand-anything/intermediate/tour.json

Project:

<projectName>

—

<projectDescription>

Languages:

<languages>

Nodes (summarized):

[list of {id, name, filePath, summary, type} for key nodes]

Layers:

[layers from Phase 4]

Key edges:

[imports and calls edges]

After the agent completes, read

$PROJECT_ROOT/.understand-anything/intermediate/tour.json

Phase 6 — REVIEW

Assemble the full KnowledgeGraph JSON object:

{
  "version": "1.0.0",
  "project": {
    "name": "<projectName>",
    "languages": ["<languages>"],
    "frameworks": ["<frameworks>"],
    "description": "<projectDescription>",
    "analyzedAt": "<ISO 8601 timestamp>",
    "gitCommitHash": "<commit hash from Phase 0>"
  },
  "nodes": [<all merged nodes from Phase 3>],
  "edges": [<all merged edges from Phase 3>],
  "layers": [<layers from Phase 4>],
  "tour": [<steps from Phase 5>]
}

1. Write the assembled graph to

   $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json

   .

2. Dispatch the graph-reviewer agent with this 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

3. After the agent completes, read

   $PROJECT_ROOT/.understand-anything/intermediate/review.json

   .

4. If

   approved: false

   :
   • Review the

     issues

     list
   • Apply automated fixes where possible:
     • Remove edges with dangling references
     • Fill missing required fields with sensible defaults (e.g., empty

       tags

       ->

       ["untagged"]

       , empty

       summary

       ->

       "No summary available"

       )
     • Remove nodes with invalid types
   • If critical issues remain after one fix attempt, save the graph anyway but include the warnings in the final report

5. If

   approved: true

   : Proceed to Phase 7.

Phase 7 — SAVE

1. Write the final knowledge graph to

   $PROJECT_ROOT/.understand-anything/knowledge-graph.json

   .

2. Write metadata to

   $PROJECT_ROOT/.understand-anything/meta.json

   :

   {
     "lastAnalyzedAt": "<ISO 8601 timestamp>",
     "gitCommitHash": "<commit hash>",
     "version": "1.0.0",
     "analyzedFiles": <number of files analyzed>
   }
   

3. Clean up intermediate files:

   rm -rf $PROJECT_ROOT/.understand-anything/intermediate
   

4. Report a summary to the user containing:

   • Project name and description
   • Files analyzed / total files
   • Nodes created (broken down by type: file, function, class)
   • Edges created (broken down by type)
   • Layers identified (with names)
   • Tour steps generated (count)
   • Any warnings from the reviewer
   • Path to the output file:

     $PROJECT_ROOT/.understand-anything/knowledge-graph.json

5. Automatically launch the dashboard by invoking the

   /understand-dashboard

   skill.

Error Handling

• If any agent dispatch fails, retry once with the same prompt plus additional context about the failure.
• 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.
• NEVER silently drop errors. Every failure must be visible in the final report.

Reference: KnowledgeGraph Schema

Node Types

file

file:<relative-path>

function

func:<relative-path>:<name>

class

class:<relative-path>:<name>

module

module:<name>

concept

concept:<name>

Edge Types (18 total)

imports

exports

contains

inherits

implements

calls

subscribes

publishes

middleware

reads_from

writes_to

transforms

validates

depends_on

tested_by

configures

related

similar_to

Edge Weight Conventions

contains

inherits

implements

calls

exports

imports

depends_on

tested_by