Inline Deterministic Validation vs Full LLM Review in Phase 6

TLDR: Inline deterministic validation runs a lightweight, rule-based script to check structural integrity at zero token cost by default, while full LLM review invokes a graph-reviewer sub-agent to perform semantic analysis and quality checks when you add the --review flag.

In the Lum1104/Understand-Anything repository, Phase 6 of the /understand pipeline serves as the final REVIEW gate before your knowledge graph reaches the dashboard. This step offers two distinct validation modes—inline deterministic validation and full LLM review—that differ fundamentally in scope, cost, and execution method. Knowing when to use each ensures you balance pipeline speed against the depth of quality assurance your graph requires.

Phase 6: The REVIEW Step

Phase 6 validates the assembled knowledge graph to prevent broken or malformed data from reaching the visualization layer. According to the skill definition in understand-anything-plugin/skills/understand/SKILL.md, this phase runs automatically after graph assembly and supports two execution paths depending on whether you need fast structural verification or deep semantic analysis.

Inline Deterministic Validation (Default)

This is the default path when running the pipeline without the --review flag.

How It Works

The orchestrator executes a pre-written, lightweight script in-process that performs strict, rule-based checks on the graph structure. As documented at line 611 of SKILL.md, this script validates critical structural elements that would otherwise break the dashboard.

What It Checks

• Dangling edges and references
• Duplicate IDs
• Missing layers or tours
• Other critical errors affecting graph integrity

Performance Characteristics

Because the script runs deterministically inside the orchestrator, it consumes virtually zero tokens and completes in milliseconds. This makes it ideal for CI environments or rapid iteration cycles where you need guaranteed syntactic correctness without API costs.

Full LLM Review (Optional)

Trigger this mode by appending the --review flag to your command.

How It Works

The orchestrator dispatches the graph-reviewer sub-agent defined in understand-anything-plugin/agents/graph-reviewer.md, feeding it the assembled graph along with the prompt template from graph-reviewer-prompt.md. As noted at line 692 of SKILL.md, this invocation allows the model to reason about the graph's semantic quality, not just its structure.

What It Checks

In addition to the deterministic structural checks, the LLM surfaces:

• Orphan nodes with no connections
• Vague or non-descriptive summaries
• Stylistic inconsistencies
• Other quality warnings that rule-based scripts cannot detect

Token Cost Implications

Unlike the inline method, full LLM review sends the entire graph to the model. According to the design specification in docs/superpowers/specs/2026-03-27-token-reduction-design.md (line 383), this consumes approximately 58,000 tokens per default run. The design document at line 316 explains this trade-off—enabling deeper feedback at significantly higher computational cost.

Command-Line Usage Examples

Use these patterns to control which validation mode executes during Phase 6.

Run the default inline validation only:

understand --full

Explicitly request the full LLM review:

understand --full --review

The first command relies on the deterministic script documented in the README at line 293, while the second triggers the graph-reviewer agent for comprehensive analysis.

Key Source Files

The logic governing these two modes spans several critical files in the repository:

• understand-anything-plugin/skills/understand/SKILL.md — Defines Phase 6 flow, inline validation (L611), and --review flag behavior (L692)
• understand-anything-plugin/agents/graph-reviewer.md — Configuration for the LLM-powered reviewer sub-agent
• understand-anything-plugin/skills/understand/graph-reviewer-prompt.md — Prompt template used when invoking the full LLM review
• README.md — High-level documentation of default validation behavior (L293)
• docs/superpowers/specs/2026-03-27-token-reduction-design.md — Design rationale for token reduction and cost analysis (L316, L383)

Summary

• Inline deterministic validation is the default, zero-cost path that runs a rule-based script to ensure structural integrity (dangling edges, duplicate IDs, missing layers).
• Full LLM review requires the --review flag, consumes approximately 58k tokens per run, and provides semantic quality checks through the graph-reviewer sub-agent.
• Choose inline validation for CI/CD pipelines and rapid iteration; use full LLM review when you need human-like quality assessment and improvement suggestions.
• Both modes execute during Phase 6 (REVIEW) but differ fundamentally in scope, cost, and the specific source files they reference in Lum1104/Understand-Anything.

Frequently Asked Questions

Does inline validation catch semantic errors like vague node summaries?

No. Inline deterministic validation only performs structural checks—removing dangling edges, deduplicating IDs, and validating layer existence. It cannot evaluate content quality, writing style, or semantic coherence. For those checks, you must trigger the full LLM review by adding the --review flag, which employs the graph-reviewer agent to analyze meaning and clarity according to the prompt defined in graph-reviewer-prompt.md.

How much does the full LLM review cost compared to the default validation?

The inline validation costs virtually zero tokens because it runs a deterministic script locally within the orchestrator. In contrast, the full LLM review sends the entire assembled graph to the model, consuming approximately 58,000 tokens per default execution according to the design document 2026-03-27-token-reduction-design.md at line 383.

Can I run both validation modes in the same pipeline execution?

No. The modes are mutually exclusive paths within Phase 6. If you omit the --review flag, the pipeline executes only the inline deterministic validation. If you include --review, the orchestrator skips the inline script and dispatches the graph-reviewer sub-agent defined in agents/graph-reviewer.md, which performs comprehensive checks including the structural validations covered by the deterministic approach.

Where is the graph-reviewer agent defined in the source code?

The agent configuration resides in understand-anything-plugin/agents/graph-reviewer.md, with its associated prompt template stored in understand-anything-plugin/skills/understand/graph-reviewer-prompt.md. These files define how the LLM interprets the graph structure and what quality criteria it applies during the full review phase.

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