{"record":{"id":"e72d4391722ae7a2","repo":"Egonex-AI/Understand-Anything","slug":"incremental-plan-or-fingerprint-patch-is-missing","errorCode":null,"errorMessage":"Incremental plan or fingerprint patch is missing","messagePattern":"Incremental plan or fingerprint patch is missing","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":390,"sourceCode":"    ...(previousProject ?? {}),\n    languages,\n    analyzedAt: new Date().toISOString(),\n    gitCommitHash: plan.headCommit,\n  };\n}\n\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') {","sourceCodeStart":372,"sourceCodeEnd":408,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L372-L408","documentation":"After resolving the project's data directory, main() reads intermediate/incremental-plan.json and intermediate/fingerprint-patch.json. If either file is missing or unparseable to a truthy object (readJson falls back to null), it throws this error: incremental finalization can only run when the /understand pipeline previously wrote both the plan and the fingerprint patch for the same run.","triggerScenarios":"Running finalize-incremental.mjs against a projectRoot whose .ua/intermediate/ (or .understand-anything/intermediate/) directory lacks incremental-plan.json or fingerprint-patch.json; running it before /understand produced the incremental artifacts; running it after intermediate files were cleaned up; pointing it at the wrong project root.","commonSituations":"Re-running finalization twice (first run cleans up the intermediate directory); a FULL_UPDATE pipeline run that never wrote a plan; invoking the script manually without having run /understand; a typo'd projectRoot so the script looks in the wrong .ua directory.","solutions":["Run the incremental /understand pipeline first so it writes incremental-plan.json and fingerprint-patch.json into the project data directory's intermediate/ subdirectory, then run the script.","Verify the projectRoot passed to the script is the analyzed project (ls <projectRoot>/.ua/intermediate/ to confirm the files exist).","If the plan is missing because a FULL_UPDATE was needed, run the full /understand pipeline instead of the incremental finalizer."],"exampleFix":"// before (intermediate artifacts already cleaned up)\nnode finalize-incremental.mjs .\n// after: re-run the pipeline stage that produces the artifacts first\n# /understand (incremental)  ->  writes .ua/intermediate/{incremental-plan,fingerprint-patch}.json\nnode finalize-incremental.mjs .","handlingStrategy":"try-catch","validationCode":"import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nconst intermediate = join(projectRoot, '.ua', 'intermediate');\nif (!existsSync(join(intermediate, 'incremental-plan.json')) || !existsSync(join(intermediate, 'fingerprint-patch.json'))) {\n  throw new Error('run the incremental /understand pipeline first');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runFinalizer(projectRoot);\n} catch (err) {\n  if (String(err.message).includes('Incremental plan or fingerprint patch is missing')) {\n    console.error('No incremental artifacts found; run /understand first or use the full pipeline.');\n    process.exit(3);\n  }\n  throw err;\n}","preventionTips":["Run the finalizer only as the last step of the incremental /understand pipeline that produced the artifacts.","Check for intermediate/incremental-plan.json and fingerprint-patch.json existence before invoking.","Don't re-run finalization after a successful run — the intermediate files are cleaned up on completion.","Confirm the projectRoot points at the analyzed project (its .ua/ directory), not a parent or sibling."],"tags":["file-not-found","missing-artifact","workflow-order"],"backgroundTag":"file-not-found","analyzedSha":"07edf82a04371b6f69779b067bdc8a1a8753a9db","analyzedAt":"2026-09-07T23:20:10.829Z","contentChangedAt":"2026-09-07T23:20:10.829Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}