{"record":{"id":"9d3730cf170d2c90","repo":"Egonex-AI/Understand-Anything","slug":"full-update-must-run-the-full-understand-pipeline","errorCode":null,"errorMessage":"FULL_UPDATE must run the full /understand pipeline","messagePattern":"FULL_UPDATE must run the full /understand pipeline","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":396,"sourceCode":"\nasync function main() {\n  const args = process.argv.slice(2);\n  if (args.length !== 1 || args[0].startsWith('--')) {\n    throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');\n  }\n  const projectRoot = realpathSync(args[0]);\n  const uaDir = resolveUaDir(projectRoot);\n  const intermediateDir = join(uaDir, 'intermediate');\n  const plan = readJson(join(intermediateDir, 'incremental-plan.json'));\n  const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));\n  const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });\n  if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');\n  if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {\n    throw new Error('Fingerprint patch does not match the incremental plan commits');\n  }\n\n  if (plan.action === 'FULL_UPDATE') {\n    throw new Error('FULL_UPDATE must run the full /understand pipeline');\n  }\n  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {\n    process.stdout.write('Generated artifacts only: analysis baseline unchanged\\n');\n    return;\n  }\n\n  const graphPath = join(uaDir, 'knowledge-graph.json');\n  const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)\n    ? plan.importMapRefreshPaths\n    : [];\n\n  if (plan.action === 'SKIP') {\n    const previousGraph = readJson(graphPath);\n    if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {\n      throw new Error('knowledge-graph.json is missing or invalid; baseline not advanced');\n    }\n    const refreshedGraph = refreshGraphImports(\n      previousGraph,","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L378-L414","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before: always finalizing\nawait run('node finalize-incremental.mjs .');\n\n// after: dispatch on the planned action\nconst plan = JSON.parse(fs.readFileSync('.ua/intermediate/incremental-plan.json'));\nif (plan.action === 'FULL_UPDATE') {\n  await runFullUnderstandPipeline();\n} else {\n  await run('node finalize-incremental.mjs .');\n}","handlingStrategy":"validation","validationCode":"const plan = JSON.parse(fs.readFileSync('.ua/intermediate/incremental-plan.json','utf8'));\nif (plan.action === 'FULL_UPDATE') {\n  throw new Error('Run the full /understand pipeline instead of incremental finalize');\n}","typeGuard":"const isIncrementalAction = (plan) =>\n  plan && plan.action !== 'FULL_UPDATE' && typeof plan.action === 'string';","tryCatchPattern":"try {\n  await run('node finalize-incremental.mjs .');\n} catch (err) {\n  if (String(err.message).includes('FULL_UPDATE must run the full')) {\n    await runFullUnderstandPipeline();\n  } else throw err;\n}","preventionTips":["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"],"tags":["incremental","pipeline","unsupported-operation"],"backgroundTag":"unsupported-operation","analyzedSha":"07edf82a04371b6f69779b067bdc8a1a8753a9db","analyzedAt":"2026-09-07T23:20:10.829Z","contentChangedAt":"2026-09-07T23:20:10.829Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}