# How the Egonex-AI Graph-Reviewer Ensures Knowledge Graph Completeness

> Discover how the Egonex-AI graph-reviewer ensures knowledge graph completeness with seven critical checks for structural soundness and data integrity.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: deep-dive
- Published: 2026-06-22

---

**The Egonex-AI graph-reviewer is a deterministic validation agent that enforces seven critical checks—including schema correctness, referential integrity, and layer coverage—to guarantee that every knowledge graph is structurally sound before publication.**

The `graph-reviewer` serves as the final quality gate in the [Egonex-AI/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) multi-agent pipeline. After the `project-scanner`, `file-analyzer`, `architecture-analyzer`, and `tour-builder` agents generate nodes, edges, layers, and guided tours, this fifth agent performs automated validation to ensure knowledge graph completeness. Only graphs with zero critical issues receive approval for interactive exploration.

## The Role of the Graph-Reviewer in the Understand Anything Pipeline

According to the pipeline definition in [`README.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/README.md), the `graph-reviewer` acts as the final arbiter before graph publication. It executes a deterministic validation script defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md) that audits the assembled knowledge graph against strict structural and semantic requirements.

The reviewer operates automatically by default after the graph assembly phase, or it can be invoked explicitly using command-line flags. It produces a JSON report at [`.understand-anything/intermediate/review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/intermediate/review.json) containing an `approved` boolean, `issues` array, `warnings` array, and detailed `stats` about the graph composition.

## Seven Critical Validation Checks for Knowledge Graph Completeness

The validation script performs seven distinct checks, each targeting specific failure modes that could compromise graph integrity.

### Schema Correctness Check

Every node and edge must contain mandatory fields with correct data types. For nodes, the script verifies the presence of `id`, `type`, `name`, `summary`, `tags`, and `complexity`. For edges, it checks `source`, `target`, `type`, `direction`, and `weight`. Missing or incorrectly typed fields generate critical issues that block approval.

### Referential Integrity Verification

All foreign key relationships must resolve to valid entities. The script validates that every `source` and `target` ID in edges, every `nodeId` in layer definitions, and every `nodeId` in tour steps points to an existing node ID. When a reference cannot be resolved, the reviewer logs the exact index or step location as a critical issue.

### Basic Completeness Requirements

The graph must contain at least one node, one edge, one layer, and one tour step. The validation script counts each collection; a zero count in any category generates a critical issue. For domain graphs containing only conceptual entities, layer and tour requirements are downgraded to warnings rather than blockers.

### Layer Coverage Validation

Every file-level node—including types `file`, `config`, `document`, `service`, `pipeline`, `table`, `schema`, `resource`, and `endpoint`—must appear in exactly one layer's `nodeIds` array. The script cross-references the node registry with layer definitions, reporting missing assignments or duplicate memberships as critical issues.

### Node ID Uniqueness Enforcement

Duplicate identifiers break graph navigation. The reviewer builds a hash map of all node IDs during traversal; any repetition immediately triggers a critical issue identifying the conflicting ID.

### Domain-Graph Detection Logic

The script automatically detects pure domain models by checking for the presence of `domain`, `flow`, or `step` node types. When these specialized nodes exist, the validation rules relax layer and tour completeness checks from critical failures to warnings, preventing false-positive rejections on high-level conceptual graphs.

### Quality Warning Collection

Non-blocking quality issues are collected in the `warnings` array for dashboard display. These include orphan nodes with no connecting edges, generic or empty summaries, self-referencing edges, and missing expected relationships for non-code node types. While these do not prevent approval, they signal opportunities for graph enrichment.

## Running the Knowledge Graph Validation Process

Execute the reviewer explicitly after analysis using the `--review` flag:

```bash
understand --review

```

For manual validation or CI/CD integration, run the generated validation script directly:

```bash
node .understand-anything/tmp/ua-graph-validate.js \
  .understand-anything/knowledge-graph.json \
  .understand-anything/tmp/ua-review-results.json

```

The script exits with a non-zero status if critical issues exist, making it suitable for automated gates in deployment pipelines.

## Understanding the Validation Report

The reviewer writes a machine-readable report that distinguishes between blocking errors and improvement suggestions:

```json
{
  "approved": true,
  "issues": [],
  "warnings": [
    "3 function nodes have no edges connecting to them",
    "Config node 'config:tsconfig.json' has no 'configures' edges"
  ],
  "stats": {
    "totalNodes": 42,
    "totalEdges": 87,
    "totalLayers": 5,
    "tourSteps": 8,
    "nodeTypes": {"file":20,"function":15,"class":7,"config":3},
    "edgeTypes": {"imports":30,"contains":40,"calls":17,"configures":5}
  }
}

```

A graph receives `"approved": true` only when the `issues` array is empty. The `stats` object provides immediate visibility into graph scale and composition ratios.

## Summary

- The **graph-reviewer** is the fifth agent in the Understand Anything pipeline, defined in [`understand-anything-plugin/agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/understand-anything-plugin/agents/graph-reviewer.md).
- It enforces **seven critical checks**: schema correctness, referential integrity, basic completeness, layer coverage, ID uniqueness, domain-graph detection, and quality warnings.
- **Zero critical issues** are required for approval; warnings do not block publication.
- The validation process can run **automatically** inline or **explicitly** via `--review` flag.
- Output is written to [`.understand-anything/intermediate/review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.understand-anything/intermediate/review.json) with boolean `approved` status and detailed `stats`.

## Frequently Asked Questions

### What happens if the graph-reviewer finds critical issues?

The knowledge graph is rejected and not published to the interactive explorer. The [`review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/review.json) file contains the specific check that failed, the offending node or edge IDs, and the file location where the error occurred. You must resolve all critical issues and regenerate the graph to achieve approval.

### How does domain-graph detection affect validation?

When the reviewer detects `domain`, `flow`, or `step` nodes, it assumes the graph represents a high-level conceptual model rather than code-level entities. In this mode, requirements for layers and tour steps are downgraded from critical errors to warnings. This prevents valid domain models from failing validation when they lack file-system-oriented layers.

### Can I run the graph-reviewer independently of the full pipeline?

Yes. While the reviewer runs automatically after the `assemble-reviewer` agent completes, you can invoke it manually using the `understand --review` command or by executing the generated Node.js validation script directly against a [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) file. This supports CI/CD gates and offline validation workflows.

### What is the difference between critical issues and warnings?

**Critical issues** represent structural defects—such as missing required fields, broken references, or duplicate IDs—that would cause runtime errors in the graph explorer. **Warnings** indicate quality concerns—such as orphan nodes or sparse summaries—that reduce graph usability but do not prevent navigation. Only critical issues block the `approved: true` status.