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

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

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.
• Phase 1 executes .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.

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 during runtime. After Phase 2, the final validation report is persisted to .understand-anything/intermediate/review.json. The complete specification for both phases lives in understand-anything-plugin/agents/graph-reviewer.md.

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