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

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, 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 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 (referenced at 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 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 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 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:

# From the repository root

understand-anything-plugin/understand --full

This creates assembled-graph.json, runs the inline validator (ua-inline-validate.cjs), and writes review.json with any detected problems.

Run the pipeline with LLM-powered graph review:

understand-anything-plugin/understand --full --review

The --review flag triggers the graph-reviewer sub-agent. The final review.json contains the LLM-generated issue list.

Inspect the validation output directly:

cat .understand-anything/intermediate/review.json

A typical output structure looks like this:

{
  "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 — 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 — Agent definition for the LLM-driven semantic audit.
• 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 — 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 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, while the LLM agent lives in 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. 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. 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.

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 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:

understand-anything-plugin/understand --full --review

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

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