What causes "FULL_UPDATE must run the full /understand pipeline" in Egonex-AI/Understand-Anything?

Run the full /understand pipeline (or /understand --full) instead of the incremental finalize step

FULL_UPDATE must run the full /understand pipeline

Error message

FULL_UPDATE must run the full /understand pipeline

What it means

The incremental finalize step is only valid for SKIP, REANALYZE-style actions. If incremental-plan.json says action === 'FULL_UPDATE', the incremental path cannot serve it and the script throws, directing the user to run the full /understand pipeline instead. This prevents a partial update from being recorded when the planner decided a full rebuild was required.

Source

Thrown at understand-anything-plugin/skills/understand/finalize-incremental.mjs:396

async function main() {
  const args = process.argv.slice(2);
  if (args.length !== 1 || args[0].startsWith('--')) {
    throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');
  }
  const projectRoot = realpathSync(args[0]);
  const uaDir = resolveUaDir(projectRoot);
  const intermediateDir = join(uaDir, 'intermediate');
  const plan = readJson(join(intermediateDir, 'incremental-plan.json'));
  const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));
  const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });
  if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');
  if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {
    throw new Error('Fingerprint patch does not match the incremental plan commits');
  }

  if (plan.action === 'FULL_UPDATE') {
    throw new Error('FULL_UPDATE must run the full /understand pipeline');
  }
  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {
    process.stdout.write('Generated artifacts only: analysis baseline unchanged\n');
    return;
  }

  const graphPath = join(uaDir, 'knowledge-graph.json');
  const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)
    ? plan.importMapRefreshPaths
    : [];

  if (plan.action === 'SKIP') {
    const previousGraph = readJson(graphPath);
    if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {
      throw new Error('knowledge-graph.json is missing or invalid; baseline not advanced');
    }
    const refreshedGraph = refreshGraphImports(
      previousGraph,

View on GitHub (pinned to 07edf82a04)

Solutions

Run the full /understand pipeline (or /understand --full) instead of the incremental finalize step
Regenerate the plan so it emits an incremental action (SKIP or reanalyze) if a full update was not intended
Check plan.action in .ua/intermediate/incremental-plan.json before invoking finalize in automation, and branch on it

Example fix

// before: always finalizing
await run('node finalize-incremental.mjs .');

// after: dispatch on the planned action
const plan = JSON.parse(fs.readFileSync('.ua/intermediate/incremental-plan.json'));
if (plan.action === 'FULL_UPDATE') {
  await runFullUnderstandPipeline();
} else {
  await run('node finalize-incremental.mjs .');
}

Defensive patterns

Strategy: validation

Validate before calling

const plan = JSON.parse(fs.readFileSync('.ua/intermediate/incremental-plan.json','utf8'));
if (plan.action === 'FULL_UPDATE') {
  throw new Error('Run the full /understand pipeline instead of incremental finalize');
}

Type guard

const isIncrementalAction = (plan) =>
  plan && plan.action !== 'FULL_UPDATE' && typeof plan.action === 'string';

Try / catch

try {
  await run('node finalize-incremental.mjs .');
} catch (err) {
  if (String(err.message).includes('FULL_UPDATE must run the full')) {
    await runFullUnderstandPipeline();
  } else throw err;
}

Prevention

Read plan.action before choosing the finalize step in automation
Never hand-edit incremental-plan.json
Dispatch FULL_UPDATE plans to the full pipeline, not finalize
Run the planner and finalize as one scripted sequence

When it happens

Trigger: Executing finalize-incremental.mjs directly on a plan whose planner emitted action 'FULL_UPDATE' (e.g. schema version change, first run with legacy graph, too many changed files).

Common situations: User forces a full update via /understand --full but a leftover script invocation runs the incremental finalize; automation wiring always calls finalize regardless of plan.action; plan file manually edited.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/9d3730cf170d2c90. Report an issue: GitHub.