Inline Validation vs --review Validation in Understand Anything: Key Differences

Inline validation runs fast, deterministic structural checks locally without LLM calls, while --review validation dispatches a Claude-powered graph reviewer for comprehensive quality analysis.

The Understand Anything repository by Egonex-AI provides two distinct validation strategies for generated knowledge graphs. The difference between inline validation and --review validation centers on speed, cost, and depth of analysis—balancing token efficiency against comprehensive AI review.

Overview of the Two Validation Modes

The orchestrator validates generated knowledge graphs through two mutually exclusive paths:

• Inline deterministic validation (default): Executed when running understand without the --review flag
• --review validation: Activated by explicitly adding the --review flag to your command

These modes differ fundamentally in implementation, cost, and the types of errors they detect.

Inline Deterministic Validation (Default Path)

When you execute the understand command without the --review flag, the system triggers inline deterministic validation. This mode executes a built-in script that scans the graph for critical structural problems using local logic only.

What It Checks

The deterministic validator catches blocking structural errors:

• Dangling references between nodes that point to non-existent targets
• Missing layers in the graph hierarchy
• Duplicate IDs that violate uniqueness constraints

These checks run entirely locally, avoiding any LLM API calls.

Implementation Details

According to the source code in understand-anything-plugin/skills/understand/SKILL.md, the default validation path is defined at line 595. The orchestrator follows this branch when $ARGUMENTS does not contain --review, executing the "Default path (no --review): inline deterministic validation" logic.

--review Validation (Full LLM Review)

Adding the --review flag switches the orchestrator to a sophisticated validation pipeline that leverages large language models for deeper analysis.

Advanced Quality Analysis

Instead of simple structural checks, the LLM reviewer—implemented as a sub-agent—analyzes the graph for higher-level quality issues:

• Orphan nodes with no meaningful connections to the graph structure
• Naming convention suggestions for better semantic clarity
• Summarization opportunities to condense redundant information
• Semantic consistency across different graph layers

These insights require reasoning capabilities that deterministic scripts cannot provide.

Implementation Details

The orchestrator checks for the --review flag at line 678 of SKILL.md and branches to the "full LLM reviewer" path. This dispatches the graph-reviewer sub-agent using the prompt template stored in understand-anything-plugin/skills/understand/graph-reviewer-prompt.md.

Token Economics and Performance

The project implements a deliberate token-reduction design documented in docs/superpowers/specs/2026-03-27-token-reduction-design.md. By defaulting to inline validation, the system saves approximately 58,000 tokens per run while still catching all blocking structural errors.

Developers can opt-in to the expensive LLM analysis only when deeper semantic insights are necessary.

How to Use Each Validation Mode

Here are the practical ways to invoke each validation strategy:

# Fast inline validation only (default) - saves ~58k tokens

understand --full

# Inline checks plus full LLM review

understand --full --review

# LLM review only on existing graph (skips deterministic checks)

understand --review

The --full flag triggers a complete graph build, while the presence of --review determines whether the graph-reviewer sub-agent activates.

Summary

• Inline validation executes deterministic structural checks locally without LLM costs, catching dangling references, missing layers, and duplicate IDs as implemented in SKILL.md line 595.
• --review validation invokes a Claude-powered agent for semantic quality analysis, surfacing orphan nodes and naming issues via the sub-agent defined at line 678.
• The default inline path saves approximately 58k tokens per run according to the token-reduction design specification.
• Use understand --review to skip rebuilding and run only the LLM reviewer on existing graphs.

Frequently Asked Questions

When should I use --review validation instead of inline validation?

Use --review when you need semantic quality checks beyond structural validation, such as verifying naming conventions, detecting orphan nodes, or getting summarization suggestions. Stick with inline validation for CI/CD pipelines where speed and token economy matter most, as it avoids the ~58k token overhead of the LLM call.

Can I run the LLM reviewer without rebuilding the graph?

Yes. Running understand --review without the --full flag skips the deterministic inline script and executes only the graph-reviewer sub-agent against the existing graph. This is useful when you want a quick quality audit without regenerating the entire knowledge graph.

What specific errors does inline validation catch compared to --review?

Inline validation catches deterministic structural errors like dangling references, missing layers, and duplicate IDs. The --review validation identifies higher-level quality issues like orphan nodes, semantic inconsistencies, and naming improvements that require LLM reasoning to detect according to the prompt defined in graph-reviewer-prompt.md.

How much more expensive is --review validation in terms of tokens?

According to the token-reduction design specification in docs/superpowers/specs/2026-03-27-token-reduction-design.md, the inline validation path saves approximately 58,000 tokens per run compared to invoking the LLM reviewer. The --review mode consumes these additional tokens to power the Claude graph analysis.

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