# REVIEW Phase Validation in Understand-Anything: Default Script and LLM Audit Modes

> Uncover REVIEW phase validation in Understand Anything. Explore default Node.js script and LLM audit modes for robust graph data integrity. Learn more now.

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

---

**The REVIEW phase performs deterministic structural validation via an inline Node.js script by default, or a semantic LLM audit via the `graph-reviewer` agent when the `--review` flag is passed.**

Understand-Anything is an open-source knowledge-graph builder that validates assembled data in Phase 6 before it ever reaches the dashboard. REVIEW phase validation ensures that `nodes`, `edges`, `layers`, and `tour` arrays are structurally sound and semantically complete. In this guide, we break down exactly what the validation checks, where the logic lives in the codebase, and how to run each mode.

## Two Modes of REVIEW Phase Validation

According to the source specification in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), the pipeline supports two distinct validation paths that converge on identical post-validation handling.

### Default Deterministic Validation (No Flag)

When no `--review` flag is supplied, the pipeline executes a deterministic Node.js script embedded in [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) at lines 78‑85. The inline validator script, `ua-inline-validate.cjs` (defined at lines 21‑84 of the same file), inspects the assembled JSON graph for structural problems. It verifies required fields, cross-references, duplicate IDs, layer-node consistency, tour-node consistency, and orphan nodes, and it produces a summary of issues, warnings, and statistics.

### LLM-Driven Semantic Review (`--review` Flag)

When the `--review` flag is present, the pipeline dispatches the `graph-reviewer` sub-agent defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) (referenced at [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) lines 98‑104). This LLM receives the full graph along with the Phase 1 scan inventory and any accumulated warnings. It then performs a semantic audit, flags missing files and extra nodes, and returns a [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) payload containing an `issues` array.

## What the Default Validation Script Checks

The deterministic validator runs seven sequential checks against the assembled graph:

1. **Basic shape checks** — ensures `nodes`, `edges`, `layers`, and `tour` are arrays; inserts empty arrays if any are missing.

2. **Node field validation** — every node must have `id`, `type`, `name`, `summary`, and at least one tag. Duplicate IDs are reported as errors.

3. **Edge reference checks** — each edge's `source` and `target` fields must point to an existing node ID.

4. **Layer-node consistency** — every entry in `layer.nodeIds` must reference an existing node, and no node may appear in more than one layer.

5. **Tour-node consistency** — each step's `nodeIds` inside the tour must reference existing nodes.

6. **Orphan detection** — nodes that have no connected edges generate a warning.

7. **Statistics collection** — counts of nodes, edges, layers, and tour steps are emitted for quick inspection.

If the script exits with a non-zero status, the pipeline reads the error output, attempts an automated fix (for example, dropping dangling edges or adding default tags), and re-runs the validation once more. Persistent failures are recorded in [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) and the dashboard launch is skipped.

## How the LLM Review (`--review`) Works

When you invoke the LLM-driven review, the pipeline changes its behavior in three stages.

### Inputs to the `graph-reviewer` Agent

The orchestrator sends the assembled graph along with the **Phase 1 scan inventory** and **any accumulated warnings** to the `graph-reviewer` agent. This gives the LLM full context of what was discovered during the initial repository scan and what problems earlier phases already flagged.

### Semantic Cross-Checks

The LLM cross-checks that every scanned file maps to a graph node and vice-versa. It flags missing files, extra nodes that do not correspond to source files, and other semantic inconsistencies that a deterministic script cannot detect.

### Output Format

Both validation paths produce a [`.understand-anything/intermediate/review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/intermediate/review.json) file. The LLM path returns an `issues` array inside that JSON, which the main orchestrator processes the same way as the deterministic script. If `issues` is empty, the pipeline proceeds to Phase 7 (SAVE); otherwise it attempts auto-fixes and may abort the auto-launch.

## Running REVIEW Phase Validation

You can trigger the REVIEW phase as part of a full analysis run. The commands differ only by the presence of the `--review` flag.

Run the full pipeline with default deterministic validation:

```bash

# From the repository root

understand-anything-plugin/understand --full

```

This creates [`assembled-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/assembled-graph.json), runs the inline validator (`ua-inline-validate.cjs`), and writes [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) with any detected problems.

Run the pipeline with LLM-powered graph review:

```bash
understand-anything-plugin/understand --full --review

```

The `--review` flag triggers the `graph-reviewer` sub-agent. The final [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) contains the LLM-generated issue list.

Inspect the validation output directly:

```bash
cat .understand-anything/intermediate/review.json

```

A typical output structure looks like this:

```json
{
  "issues": [],
  "warnings": ["Node 'file:src/utils.ts' has no edges (orphan)"],
  "stats": {
    "totalNodes": 342,
    "totalEdges": 1245,
    "totalLayers": 7,
    "tourSteps": 12,
    "nodeTypes": {"file":210,"config":45,"document":87},
    "edgeTypes": {"imports":540,"calls":300,"configures":405}
  }
}

```

## Key Source Files for REVIEW Phase Validation

- [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) — Central specification of all phases. Lines 78‑85 define the default validator invocation, lines 21‑84 contain the inline `ua-inline-validate.cjs` script, and lines 98‑104 define the `--review` LLM dispatch.
- [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) — Agent definition for the LLM-driven semantic audit.
- [`understand-anything-plugin/agents/assemble-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/assemble-reviewer.md) — Related sub-agent that reviews the assembled graph before the final REVIEW phase.
- [`understand-anything-plugin/src/context-builder.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/context-builder.ts) — Indirectly supplies the combined graph data that feeds into both validation paths.
- `understand-anything-plugin/scripts/generate-large-graph.mjs` — Utility for generating test graphs to exercise the REVIEW validation at scale.

These files together implement the robust validation pipeline that guarantees the knowledge graph is well-formed before it is rendered in the dashboard.

## Summary

- The REVIEW phase is Phase 6 of the Understand-Anything pipeline and acts as the final gate before rendering the dashboard.
- **Default mode** executes a deterministic Node.js inline script (`ua-inline-validate.cjs`) that checks graph shape, node fields, edge references, layer consistency, tour consistency, and orphan nodes.
- **`--review` mode** dispatches the `graph-reviewer` LLM agent to perform a semantic audit against the Phase 1 scan inventory and accumulated warnings.
- Both modes produce a [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) file; if issues are found, the pipeline attempts one round of automated fixes before aborting the dashboard launch.
- The validation specification and inline script reside in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), while the LLM agent lives in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).

## Frequently Asked Questions

### What files does the REVIEW phase validate?

The REVIEW phase validates the assembled knowledge graph, typically stored in [`assembled-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/assembled-graph.json). It inspects the `nodes`, `edges`, `layers`, and `tour` arrays for structural integrity and semantic consistency.

### Where is the REVIEW phase validation logic defined?

The validation logic is specified in [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md). The default inline validator script appears at lines 21‑84, the default dispatch is at lines 78‑85, and the `--review` LLM dispatch is at lines 98‑104. The `graph-reviewer` agent is defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).

### Does the REVIEW phase try to fix errors automatically?

Yes. If the deterministic script exits with a non-zero status or the LLM review returns issues, the pipeline attempts an automated fix (such as dropping dangling edges or adding default tags) and re-runs the validation once. Persistent failures are written to [`review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/review.json) and the dashboard launch is skipped.

### How do I run the LLM-powered review instead of the default script?

Append the `--review` flag to your understand command:

```bash
understand-anything-plugin/understand --full --review

```

This triggers the `graph-reviewer` sub-agent rather than the deterministic inline validator.