# How the Graph-Reviewer Agent Validates the Knowledge Graph in Understand-Anything

> Learn how the graph-reviewer agent validates the JSON knowledge graph in Understand Anything. It uses a two-phase pipeline for schema compliance, integrity, and quality checks, ensuring critical issue resolution.

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

---

**The graph-reviewer agent validates the JSON knowledge graph through a two-phase pipeline: first, it generates and executes a deterministic Node.js validation script that checks schema compliance, referential integrity, completeness, and quality heuristics; then it consumes the script's JSON output to approve or reject the graph based solely on whether critical issues exist.**

In the Understand-Anything pipeline, the **graph-reviewer agent** serves as the quality gate for the generated JSON knowledge graph. According to the agent specification in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md), it enforces structural soundness through a strict deterministic validation process before downstream agents or the dashboard can consume the graph. Only graphs that pass all critical checks receive approval, while warnings are tolerated but reported.

## Phase 1: The Deterministic Validation Script

The first phase generates a Node-oriented script — typically Node.js — at [`.understand-anything/tmp/ua-graph-validate.js`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/tmp/ua-graph-validate.js). This script receives the graph file path as `process.argv[2]` and writes its results to `process.argv[3]`. It exits with code `0` if execution succeeds or `1` if a runtime error occurs, such as an unreadable file.

The script writes a JSON object containing `scriptCompleted`, `issues`, `warnings`, and a `stats` summary that includes node and edge counts plus type distributions. Critical issues populate the `issues` array, while non-critical concerns populate `warnings`.

### Schema Validation

Every node must contain `id`, `type`, `name`, `summary`, `tags`, and `complexity` with correct types. Every edge must contain `source`, `target`, `type`, `direction`, and `weight`. Violations are treated as **critical** issues.

### Referential Integrity

All edge `source` and `target` IDs, layer `nodeIds`, and tour-step `nodeIds` must point to existing node IDs. Broken references are flagged as **critical**.

### Completeness

The graph must contain at least one node, one edge, one layer, and one tour step. For domain graphs, missing layers or tour steps are downgraded to warnings, while the absence of nodes or edges remains critical across all graph types.

### Layer Coverage

For structural graphs, each file-level node must appear in exactly one layer's `nodeIds`, and layers must not be empty. Violations are treated as **critical** issues.

### Uniqueness

Duplicate node IDs are not permitted. The script enforces **uniqueness** across all node identifiers as a critical check.

### Quality and Consistency Heuristics

Several warning-level checks improve graph quality:

- **Tour validation**: Tour steps must be sequential, unique, contain at least one node, and total between 5 and 15 steps.
- **Quality checks**: Detect empty or file-name-only summaries, self-referencing edges, and orphan nodes.
- **Non-code node quality**: Warn when expected edge types are missing for config, service, pipeline, table, schema, domain, or flow nodes.
- **Node-type and ID-prefix consistency**: Verify that a node's `type` matches its ID prefix, such as `type: "config"` requiring an `id` that starts with `config:`.

## Phase 2: Review and Approval Logic

After the script completes, the graph-reviewer agent consumes the generated JSON output and completely ignores the original graph file. This design ensures the decision is based entirely on the deterministic script results.

### Approval Criteria

The agent applies strict boolean logic:

- If the `issues` array is empty, the graph receives `approved: true`.
- If any critical issue is present, the graph receives `approved: false`.

Warnings do not block approval but remain visible in the final report for downstream consumers.

### Final Report Output

The agent writes the final validation report to `<project-root>/.understand-anything/intermediate/review.json`. This file omits the `scriptCompleted` flag and contains the definitive approval status along with collected issues, warnings, and statistics.

## Validation Script Execution Example

The following example demonstrates how the generated validation script is invoked and how results are consumed in practice:

```js
const graphPath = "/path/to/graph.json";
const outPath   = "/path/to/.understand-anything/tmp/ua-review-results.json";

require("child_process").execSync(
  `node .understand-anything/tmp/ua-graph-validate.js "${graphPath}" "${outPath}"`
);

// After execution, read the result:
const result = JSON.parse(require("fs").readFileSync(outPath, "utf8"));
if (result.approved) {
  console.log("✅ Graph approved", result.stats);
} else {
  console.error("❌ Graph rejected – issues:", result.issues);
}

```

This pattern isolates validation logic in a standalone executable, letting the agent treat the script output as the single source of truth for graph quality.

## Summary

- The graph-reviewer agent runs a two-phase validation pipeline specified in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).
- Phase 1 executes [`.understand-anything/tmp/ua-graph-validate.js`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/tmp/ua-graph-validate.js), which receives the graph path via `process.argv[2]` and writes results to `process.argv[3]`.
- Critical checks include schema validation, referential integrity, completeness, uniqueness, and layer coverage, while warnings cover tour validation, summary quality, and node-type consistency.
- Phase 2 consumes the script's JSON output and approves the graph only when the `issues` array is empty.
- The final approval report is written to [`.understand-anything/intermediate/review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/intermediate/review.json).

## Frequently Asked Questions

### What checks does the graph-reviewer validation script perform?

The script performs nine checks divided into critical and warning categories. Critical checks enforce schema compliance, referential integrity, completeness, layer coverage, and unique node IDs. Warning-level checks validate tour step sequences, detect low-quality summaries and orphan nodes, ensure expected edges for non-code nodes, and verify that node `type` values match their ID prefixes.

### How does the graph-reviewer agent decide to approve or reject a knowledge graph?

The agent reads the JSON output produced by the validation script and ignores the original graph file. If the `issues` array is empty, the agent sets `approved: true`; if any critical issue exists, it sets `approved: false`. Warnings are reported but do not influence the boolean approval decision.

### What is the difference between a critical issue and a warning in Understand-Anything validation?

Critical issues represent structural failures that compromise graph integrity, such as schema violations, broken references, duplicate IDs, or incomplete structural data. Warnings indicate quality concerns — such as invalid tour lengths, self-referencing edges, or missing expected edge types — that are reported for human review but do not block automated approval.

### Where are the validation script and final report stored?

The agent generates the validation script at [`.understand-anything/tmp/ua-graph-validate.js`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/tmp/ua-graph-validate.js) during runtime. After Phase 2, the final validation report is persisted to [`.understand-anything/intermediate/review.json`](https://github.com/Lum1104/Understand-Anything/blob/main/.understand-anything/intermediate/review.json). The complete specification for both phases lives in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).