How Guided Tour Generation Works in Understand Anything Phase 5

Guided tour generation in Understand Anything Phase 5 constructs a navigational walkthrough of a codebase by prompting an LLM to create ordered tour steps, parsing the JSON response, and falling back to a deterministic topological sort if the LLM fails.

The Egonex-AI/Understand-Anything repository implements this feature during the "summarize" stage (Phase 5) of its analysis pipeline. The system transforms the internal KnowledgeGraph into a consumable tour format that helps developers navigate complex codebases by highlighting specific nodes and providing contextual explanations.

The Three-Stage Tour Generation Pipeline

The guided tour generation logic resides in tour-generator.ts and operates through three distinct phases: prompt construction, LLM response parsing, and heuristic fallback.

Prompt Construction with buildTourGenerationPrompt

The function buildTourGenerationPrompt accepts the complete KnowledgeGraph—containing project metadata, nodes, edges, and optional layers—and formats a detailed prompt for a large-language model. The prompt requests a JSON-encoded list of tour steps, where each step must include:

• An order number
• A title and description
• The IDs of nodes to highlight
• An optional language-specific lesson

This structured request ensures the LLM returns data that the system can directly map to UI components.

LLM Response Parsing via parseTourGenerationResponse

The raw LLM reply is fed to parseTourGenerationResponse, which extracts the JSON object even if wrapped in Markdown code fences. The parser validates each step against the expected schema, discarding malformed entries. Only valid TourStep objects proceed to the final array.

Heuristic Fallback using generateHeuristicTour

If the LLM call fails or the repository is being processed offline, generateHeuristicTour builds a deterministic tour from graph topology:

1. Separate concept nodes from regular code nodes
2. Create adjacency and in-degree maps from the edges
3. Run Kahn's topological sort to obtain a dependency-respecting order
4. Group nodes by layer if defined; otherwise batch three nodes per step
5. Append a "Key Concepts" step for concept nodes
6. Assign sequential order numbers to all steps

This ensures users always receive a navigable tour even without LLM availability.

Implementation Details and Code Examples

The following pattern demonstrates the complete flow from prompt generation to final tour array:

// 1️⃣ Build the LLM prompt from the graph
import { buildTourGenerationPrompt } from "./tour-generator";
const prompt = buildTourGenerationPrompt(knowledgeGraph);

// 2️⃣ Send the prompt to the LLM (pseudo-code – the real call lives in the agent layer)
const llmResponse = await llmClient.complete({ prompt });

// 3️⃣ Try to parse the LLM response
import { parseTourGenerationResponse } from "./tour-generator";
let tour = parseTourGenerationResponse(llmResponse);

// 4️⃣ If parsing fails, fall back to the heuristic generator
if (tour.length === 0) {
  import { generateHeuristicTour } from "./tour-generator";
  tour = generateHeuristicTour(knowledgeGraph);
}

// 5️⃣ The `tour` array is now ready for the UI
console.log("Guided tour steps:", tour);

The onboarding builder in src/onboard-builder.ts integrates this tour into the final skill output:

// Inside src/onboard-builder.ts (simplified)
const tour = await generateTour(graph);
lines.push("Follow this guided tour to understand the codebase:");
lines.push(JSON.stringify(tour, null, 2));

Key Source Files

The guided tour generation system spans three primary files in the Understand Anything codebase:

• understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts – Implements buildTourGenerationPrompt, parseTourGenerationResponse, and generateHeuristicTour
• understand-anything-plugin/src/onboard-builder.ts – Integrates the generated tour into the final "onboard" skill output
• understand-anything-plugin/packages/core/src/types.ts – Defines KnowledgeGraph, TourStep, and related type information

Summary

• Guided tour generation in Phase 5 creates navigational walkthroughs from the KnowledgeGraph
• buildTourGenerationPrompt constructs LLM prompts requesting JSON-encoded tour steps
• parseTourGenerationResponse extracts and validates JSON responses, handling Markdown code fences
• generateHeuristicTour provides a deterministic fallback using Kahn's topological sort on graph dependencies
• The tour is finalized in onboard-builder.ts and delivered to the dashboard UI

Frequently Asked Questions

What triggers the heuristic fallback in tour generation?

The system invokes generateHeuristicTour when parseTourGenerationResponse returns an empty array, which occurs if the LLM call fails, produces malformed JSON, or when the repository is processed offline without LLM access.

What data structure represents a single tour step?

According to types.ts, each TourStep object contains an order number, title, description, an array of node IDs to highlight, and an optional language-specific lesson string.

How does the heuristic generator determine the order of tour steps?

generateHeuristicTour uses Kahn's topological sort algorithm on the dependency graph to ensure files are visited only after their dependencies have been explained, creating a logically coherent learning path.

Where is the generated tour integrated into the final output?

The onboard-builder.ts file consumes the tour array and appends it to the final skill output, formatting it as a JSON string that the dashboard UI renders as an interactive guided tour.

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