# How Guided Tour Generation Works in Understand Anything Phase 5

> Discover how guided tour generation in Understand Anything Phase 5 uses LLM prompting and fallback topological sort to create codebase walkthroughs. Learn more.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-27

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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:

```typescript
// 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/onboard-builder.ts) integrates this tour into the final skill output:

```typescript
// 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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/packages/core/src/analyzer/tour-generator.ts)** – Implements `buildTourGenerationPrompt`, `parseTourGenerationResponse`, and `generateHeuristicTour`
- **[`understand-anything-plugin/src/onboard-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.