# How the Graph Validation Review Process Works: Inline vs. LLM Validation

> Understand your graph validation process. Learn how inline checks and optional LLM review ensure knowledge graph accuracy within the Understand Anything pipeline.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: deep-dive
- Published: 2026-06-02

---

**The Understand-Anything pipeline validates knowledge graphs through deterministic inline checks on every run, while optional LLM-powered review provides semantic analysis when users specify the `--review` flag.**

The `understand-anything` repository constructs a knowledge graph from your codebase and validates it before delivering results to the dashboard. This **graph validation review process** operates through two distinct phases: a fast, deterministic inline check that runs automatically after graph assembly, and an optional deep review powered by an LLM sub-agent triggered by explicit user request.

## How Inline Validation Works

Inline validation executes immediately after the graph builder produces the JSON structure. This deterministic phase ensures structural integrity before any expensive operations occur.

The orchestrator invokes `validateGraph()` from **[`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts)** (line 499). This function applies Zod-style schema validation to verify node and edge types, required fields, and referential integrity. It checks that all edge targets exist as valid nodes and detects duplicate IDs within the graph structure.

If validation fails, the function returns a `ValidationResult` object containing specific errors and warnings. The orchestrator stores these in the `$PHASE_WARNINGS` variable and includes them directly in the final output report. You can optionally disable this check by passing `{ validate: false }`, as implemented in **[`packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/persistence/index.ts)** (lines 94-95), though this is rarely recommended.

## How LLM-Powered Review Works

When you append the `--review` flag to commands like `understand --full --review`, the pipeline activates the `graph-reviewer` sub-agent for semantic analysis.

The orchestrator dispatches this agent (defined in **[`agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/graph-reviewer.md)**) along with the assembled graph and accumulated `$PHASE_WARNINGS`. The sub-agent processes natural language instructions from **[`skills/understand/graph-reviewer-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/graph-reviewer-prompt.md)**, analyzing the graph for semantic duplicates, missing documentation, and suspicious edge weights that static schemas cannot express.

The LLM generates a human-readable report that the orchestrator merges with inline warnings, presenting a comprehensive validation output that combines structural and semantic assessments.

## Why the Validation Pipeline Uses Two Phases

The split between inline and LLM validation serves three critical architectural purposes:

- **Performance and token cost.** Inline validation runs in milliseconds using pure JavaScript and consumes zero LLM tokens. Transmitting graphs exceeding 500 nodes to an LLM can consume tens of thousands of tokens, making the gated approach essential for cost-effective default workflows.
- **Deterministic baselines.** The schema guarantees structural correctness on every execution, providing developers with a reliable, reproducible foundation that never varies between runs.
- **Semantic insight.** The LLM identifies subtle logical errors—such as duplicated services, incomplete documentation, or anomalous edge weights—that deterministic rules cannot practically express.

## Code Implementation Examples

Implement inline validation using the core schema module:

```typescript
import { validateGraph } from '@understand-anything/core/schema';

// After the graph is built:
const result = validateGraph(assembledGraph);
if (result.issues.length) {
  // handle warnings or abort pipeline
  console.error('Validation failed:', result.issues);
}

```

Conditionally trigger LLM review based on user arguments:

```typescript
if (ARGUMENTS.includes('--review')) {
  await dispatchSubagent('graph-reviewer', {
    promptFile: 'skills/understand/graph-reviewer-prompt.md',
    graph: assembledGraph,
    priorWarnings: phaseWarnings,
  });
}

```

## Summary

- **Inline validation** always runs via `validateGraph` in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts) to verify JSON structure, referential integrity, and ID uniqueness.
- **LLM review** only activates with the `--review` flag, utilizing the `graph-reviewer` sub-agent defined in [`agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/graph-reviewer.md).
- The **graph-reviewer prompt** lives in [`skills/understand/graph-reviewer-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/graph-reviewer-prompt.md) and handles semantic analysis beyond schema constraints.
- Validation can be programmatically disabled via `{ validate: false }` in [`packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/persistence/index.ts) (lines 94-95).
- The two-phase approach balances execution speed and API costs against deep semantic insight.

## Frequently Asked Questions

### What is the difference between inline and LLM graph validation?

Inline validation uses deterministic TypeScript/Zod schema checks in [`packages/core/src/schema.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/schema.ts) to verify JSON structure and referential integrity. LLM validation sends the assembled graph to a sub-agent that runs [`skills/understand/graph-reviewer-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/graph-reviewer-prompt.md) to detect semantic issues like duplicate services or missing documentation that static rules cannot express.

### When does the LLM validation run?

LLM validation runs only when you explicitly include the `--review` flag in your command (for example, `understand --full --review`). Without this flag, the pipeline executes only the inline validation phase to minimize latency and token costs.

### Can I disable the inline validation step?

Yes, though this is rarely recommended. You can pass `{ validate: false }` to skip the schema check, as implemented in [`packages/core/src/persistence/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/core/src/persistence/index.ts) lines 94-95. Disabling validation risks propagating structural errors downstream to the dashboard.

### How does the LLM reviewer know what to check?

The orchestrator feeds the sub-agent instructions from [`skills/understand/graph-reviewer-prompt.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/graph-reviewer-prompt.md). This prompt template contains natural-language instructions guiding the LLM to examine edge weights, identify semantic duplicates, and flag documentation gaps that the deterministic validator cannot catch.