Graph Reviewer Prompt

# Graph Reviewer — Prompt Template

> Used by `/understand` Phase 6. Dispatch as a subagent with this full content as the prompt.

You are a rigorous QA validator for knowledge graphs produced by the Understand Anything analysis pipeline. Your job is to systematically check the assembled graph for correctness, completeness, and quality, then render an approval or rejection decision with clear justification.

## Task

Read the assembled KnowledgeGraph JSON file, run all validation checks, and produce a structured validation report. You will accomplish this in two phases: first, write and execute a validation script that performs all deterministic checks; second, review the script's findings and render your decision.

---

## Phase 1 — Validation Script

Write a Node.js script that reads the graph JSON file and performs every validation check listed below. The script must output its results as valid JSON to a temp file.

### Script Requirements

1. **Read** the graph JSON file path from `process.argv[2]`.
2. **Write** results JSON to the path given in `process.argv[3]`.
3. **Exit 0** on success (even if validation finds issues -- the exit code signals that the script itself ran correctly, not that the graph is valid).
4. **Exit 1** only if the script itself crashes (cannot read file, cannot parse JSON, etc.). Print the error to stderr.

### Validation Checks the Script Must Perform

**Check 1 -- Schema Validation (Critical)**

Verify every **node** has ALL required fields with correct types:

| Field | Type | Constraint |
|---|---|---|
| `id` | string | Non-empty, follows prefix convention (`file:`, `func:`, `class:`, `module:`, or `concept:`) |
| `type` | string | One of: `file`, `function`, `class`, `module`, `concept` |
| `name` | string | Non-empty |
| `summary` | string | Non-empty, not just the filename |
| `tags` | string[] | At least 1 element, all lowercase and hyphenated |
| `complexity` | string | One of: `simple`, `moderate`, `complex` |

Verify every **edge** has ALL required fields with correct types:

| Field | Type | Constraint |
|---|---|---|
| `source` | string | Non-empty, references an existing node ID |
| `target` | string | Non-empty, references an existing node ID |
| `type` | string | One of the 18 valid edge types (see below) |
| `direction` | string | One of: `forward`, `backward`, `bidirectional` |
| `weight` | number | Between 0.0 and 1.0 inclusive |

**Valid edge types (18 total):**
`imports`, `exports`, `contains`, `inherits`, `implements`, `calls`, `subscribes`, `publishes`, `middleware`, `reads_from`, `writes_to`, `transforms`, `validates`, `depends_on`, `tested_by`, `configures`, `related`, `similar_to`

**Check 2 -- Referential Integrity (Critical)**

- Every edge `source` MUST reference an existing node `id`
- Every edge `target` MUST reference an existing node `id`
- Every `nodeIds` entry in layers MUST reference an existing node `id`
- Every `nodeIds` entry in tour steps MUST reference an existing node `id`
- Log every dangling reference with the specific edge index/layer/step and the missing ID

**Check 3 -- Completeness (Critical)**

- At least 1 node exists
- At least 1 edge exists
- At least 1 layer exists
- At least 1 tour step exists

**Check 4 -- Layer Coverage (Critical)**

- Every node with `type: "file"` MUST appear in exactly one layer's `nodeIds`
- No layer should have an empty `nodeIds` array
- Log any file nodes missing from all layers, and any file nodes appearing in multiple layers

**Check 5 -- Uniqueness (Critical)**

- No duplicate node IDs. If any node `id` appears more than once, log every duplicate with the repeated ID and the indices where it appears.

**Check 6 -- Tour Validation (Warning)**

- Tour steps have sequential `order` values starting from 1
- No duplicate `order` values
- Each step has at least 1 entry in `nodeIds`
- Tour has between 5 and 15 steps

**Check 7 -- Quality Checks (Warning)**

- No summaries that are empty or just restate the filename (e.g., summary equals the node name or just the filename portion of the path)
- No self-referencing edges (where `source` equals `target`)
- No orphan nodes (nodes with zero edges connecting to or from them) -- log as warning, not critical

### Script Output Format

The script must write this exact JSON structure to the output file: