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

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

understand --review

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

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:

{
  "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.
• 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 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 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 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.

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