How the Guided Tour Generator in Understand-Anything Determines Learning Order

The guided tour generator creates a dependency-aware learning path by analyzing the project's knowledge graph, scoring modules by complexity, and topologically sorting them to ensure foundational concepts appear before dependents.

The Egonex-AI/Understand-Anything repository features a sophisticated guided tour generator that automatically constructs step-by-step learning paths for complex codebases. This system, implemented primarily by the tour-builder agent, determines the optimal learning order by parsing structural relationships and calculating complexity metrics. Understanding this process helps developers customize their onboarding experience and debug tour generation issues.

Three-Phase Architecture for Determining Learning Order

The guided tour generator operates through a structured three-phase pipeline that transforms raw source code into an ordered educational experience.

Phase 1: Project Scanning and Knowledge Graph Construction

The process begins with the project-scanner agent, which walks the repository and parses source files using tree-sitter. This agent extracts symbols, imports, and export relationships from the codebase.

All discovered entities become nodes in a knowledge graph stored at .understand-anything/knowledge-graph.json. Edges in this graph encode "depends-on" relationships, where A → B indicates that module A imports or depends on module B. This graph structure serves as the foundation for all subsequent ordering decisions.

Phase 2: Dependency Weighting and Prioritization

Once the graph is constructed, the tour-builder assigns a complexity score to each node. The scoring algorithm considers multiple factors:

• Depth – The longest path from a leaf node, measuring how many transitive dependencies a module has.
• Fan-in / Fan-out – The number of incoming and outgoing edges, where high fan-in indicates a core utility used by many components.
• File size and type – Smaller utility files receive lower weights than large components.

Nodes are sorted by descending score, with alphabetical ordering used to break ties and ensure deterministic output.

Phase 3: Topological Sorting and Tour Generation

The final phase applies a topological sort to the weighted graph, ensuring every module appears after all of its dependencies. This algorithm respects the dependency relationships established in phase 1 while incorporating the complexity rankings from phase 2.

The sorted list transforms into discrete tour steps, each containing a description, code-snippet preview, and link to the file viewer. The complete tour serializes to .understand-anything/tour.json and renders in the dashboard's Info sidebar via src/onboard-builder.ts.

Key Implementation Files

The guided tour generator relies on several critical components across the codebase:

Component	File Path	Role
Tour-builder logic	agents/tour-builder.md	Defines the scoring algorithm and ordering logic.
Project scanning	agents/project-scanner.md	Walks the repository and constructs the knowledge graph.
Knowledge-graph schema	packages/core/schema.ts	Provides TypeScript types for nodes and edges.
Dashboard integration	src/onboard-builder.ts	Renders tour steps in the UI.
Graph utilities	src/context-builder.ts	Supplies topological sort and traversal helpers.

Triggering Tour Generation

The guided tour workflow activates automatically after a successful /understand run. From the CLI, you can trigger full analysis and tour generation with:

// Example: invoking a guided tour from the CLI
await runCommand('/understand --full'); // triggers analysis → tour generation

This command initiates the project scanning phase and propagates through the complete pipeline to generate the final tour.

Working with the Tour Data

Developers can interact with the generated tour programmatically. The tour-builder imports graph utilities from context-builder.ts to perform the topological sorting:

// Inside tour-builder (simplified)
import { topologicalSort } from './context-builder';
import { Graph } from '@understand-anything/core';

// Build weighted list
const weighted = graph.nodes.map(n => ({
  id: n.id,
  weight: computeScore(n, graph)   // depth, fan‑in/out, size…
}));

// Sort respecting dependencies
const ordered = topologicalSort(weighted, graph.edges);

The resulting ordered array determines the sequence of steps presented to learners.

Summary

• The guided tour generator constructs a knowledge graph by parsing the repository with tree-sitter and extracting dependency relationships.
• It calculates complexity scores based on depth, fan-in/fan-out, and file size to prioritize learning modules.
• A topological sort ensures that every module appears after its dependencies, creating a logical learning progression.
• The final tour serializes to .understand-anything/tour.json and renders in the dashboard sidebar.

Frequently Asked Questions

What file stores the generated knowledge graph?

The project-scanner agent outputs the dependency graph to .understand-anything/knowledge-graph.json. This file contains all nodes representing code entities and edges encoding "depends-on" relationships used by the tour-builder to determine learning order.

How does the generator calculate which module to show first?

The tour-builder assigns complexity scores based on three metrics: depth (transitive dependency chain length), fan-in/fan-out (connectivity to other modules), and file size. Modules with the highest scores—typically foundational utilities with high fan-in—appear earliest in the sequence, provided they have no unmet dependencies in the topological sort.

What ensures that dependencies are learned before dependents?

The topological sort algorithm implemented in src/context-builder.ts guarantees that every module appears in the tour only after all its dependencies have been presented. This respects the directional edges in the knowledge graph where A → B indicates A depends on B.

How do I trigger the guided tour generation process?

The tour generation process triggers automatically following a successful /understand command execution. Use the --full flag to initiate the complete pipeline from project scanning through tour serialization, as implemented in the CLI command handler.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}