{"record":{"id":"8d9d0f06899b7409","repo":"Egonex-AI/Understand-Anything","slug":"symbol-retry-requires-a-partial-or-architecture-in","errorCode":null,"errorMessage":"Symbol retry requires a partial or architecture incremental update","messagePattern":"Symbol retry requires a partial or architecture incremental update","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/prepare-symbol-retry.mjs","lineNumber":23,"sourceCode":"import { existsSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';\nimport { spawnSync } from 'node:child_process';\nimport {\n  atomicWriteJson,\n  getIntermediateDir,\n  loadSymbolContext,\n  normalizePath,\n  readJson,\n  symbolKind,\n  validateIncrementalSymbols,\n} from './validate-incremental-symbols.mjs';\n\nasync function main() {\n  if (process.argv.length !== 3) throw new Error('Usage: node prepare-symbol-retry.mjs <projectRoot>');\n  const projectRoot = realpathSync(process.argv[2]);\n  const intermediateDir = await getIntermediateDir(projectRoot);\n  const { plan, baseline } = loadSymbolContext(projectRoot, intermediateDir);\n  if (!['PARTIAL_UPDATE', 'ARCHITECTURE_UPDATE'].includes(plan.action)) {\n    throw new Error('Symbol retry requires a partial or architecture incremental update');\n  }\n  const retryPath = join(intermediateDir, 'incremental-symbol-retry.json');\n  if (existsSync(retryPath)) {\n    const retry = readJson(retryPath);\n    if (retry.baseCommit === plan.baseCommit && retry.headCommit === plan.headCommit && retry.attempt === 1) {\n      throw new Error('Symbol retry already used for these commits; stop without advancing the baseline');\n    }\n  }\n  // Do not trust an old report or a caller-supplied list of files to replace.\n  const report = await validateIncrementalSymbols(projectRoot, { intermediateDir });\n  if (report.ok || report.unresolvedFiles.length === 0) {\n    throw new Error('No unresolved symbol files eligible for a targeted retry; inspect the symbol report');\n  }\n  const paths = new Set(report.unresolvedFiles);\n  const changedFilesPath = join(intermediateDir, 'incremental-symbol-retry-files.json');\n  const batchesPath = join(intermediateDir, 'incremental-symbol-retry-batches.json');\n  atomicWriteJson(changedFilesPath, [...paths]);\n  const skillDir = dirname(fileURLToPath(import.meta.url));","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/prepare-symbol-retry.mjs#L5-L41","documentation":"The symbol retry mechanism is only valid for incremental plans whose action is PARTIAL_UPDATE or ARCHITECTURE_UPDATE. After loading the persisted plan, the script validates plan.action against this whitelist and throws when the action is anything else (e.g. FULL_REBUILD), because a targeted symbol retry is meaningless or unsafe for that update type.","triggerScenarios":"Running prepare-symbol-retry.mjs in a project whose intermediate incremental-symbol-retry/plan state records an action other than PARTIAL_UPDATE or ARCHITECTURE_UPDATE — most commonly after a full rebuild was planned, or after the plan file was written by a different pipeline stage.","commonSituations":"Developer assumed retry works after any failure, but the last plan was a FULL_REBUILD; stale plan file in the data directory from an older run with a different action; hand-edited or migrated intermediate state.","solutions":["Check the persisted plan's action (intermediate dir plan JSON) and only run symbol retry when it is PARTIAL_UPDATE or ARCHITECTURE_UPDATE.","For other actions (e.g. full rebuild), re-run the corresponding prepare step instead of the symbol retry script.","If the plan file is stale, regenerate it by re-running the incremental prepare for the current commits, then retry."],"exampleFix":"// before\n// plan.action === 'FULL_REBUILD'\nnode prepare-symbol-retry.mjs .\n// Error: Symbol retry requires a partial or architecture incremental update\n// after: rerun the matching prepare step first\nnode prepare-incremental.mjs .   # produces PARTIAL_UPDATE plan\nnode prepare-symbol-retry.mjs .  # passes","handlingStrategy":"validation","validationCode":"import { existsSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nconst plan = JSON.parse(readFileSync(join(intermediateDir, 'incremental-plan.json'), 'utf-8'));\nif (!['PARTIAL_UPDATE', 'ARCHITECTURE_UPDATE'].includes(plan.action)) {\n  throw new Error(`Skip symbol retry; plan.action=${plan.action}`);\n}","typeGuard":"const isRetryablePlan = (plan) =>\n  plan && (plan.action === 'PARTIAL_UPDATE' || plan.action === 'ARCHITECTURE_UPDATE');","tryCatchPattern":"try {\n  await runRetry(projectRoot);\n} catch (e) {\n  if (e.message.includes('Symbol retry requires a partial or architecture')) {\n    // fall back to the prepare step matching the plan's action\n  } else throw e;\n}","preventionTips":["Check the plan's action in the intermediate dir before invoking the retry script.","Route FULL_REBUILD failures to the full-rebuild flow, not symbol retry.","Regenerate stale plan files before retrying."],"tags":["retry","invalid-enum-value","incremental-update","state-machine"],"backgroundTag":"invalid-enum-value","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"}