{"record":{"id":"9da980399716324a","repo":"pbakaus/impeccable","slug":"usage-surface-brief-mjs-write-primary-target-b-9da980","errorCode":null,"errorMessage":"usage: surface-brief.mjs write <primary-target> <body-file>","messagePattern":"usage: surface-brief\\.mjs write <primary-target> <body-file>","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"skill/scripts/surface-brief.mjs","lineNumber":45,"sourceCode":"    if (!filePath) throw new Error('surface brief path requires a concrete target');\n    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\\n`);\n    return;\n  }\n  if (command === 'list') {\n    process.stdout.write(`${JSON.stringify(listSurfaceBriefs(projectRoot).map((brief) => summary(brief, projectRoot)), null, 2)}\\n`);\n    return;\n  }\n  if (command === 'read') {\n    const result = resolveSurfaceBrief(projectRoot, target || null);\n    if (result.brief) {\n      process.stdout.write(result.brief.text);\n      return;\n    }\n    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\\n`);\n    process.exit(2);\n  }\n  if (command === 'write') {\n    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');\n    const filePath = writeSurfaceBrief({\n      projectRoot,\n      primaryTarget: target,\n      relatedTargets,\n      body: fs.readFileSync(bodyFile, 'utf-8'),\n    });\n    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\\n`);\n    return;\n  }\n  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');\n}\n\nfunction isMainModule() {\n  if (!process.argv[1]) return false;\n  try {\n    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);\n  } catch {\n    return import.meta.url === pathToFileURL(process.argv[1]).href;","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/skill/scripts/surface-brief.mjs#L27-L63","documentation":"Thrown by main() in surface-brief.mjs when the 'write' subcommand is invoked without either the primary target or the body-file argument. The write command persists a brief to disk and needs both: the target names the surface the brief describes, and bodyFile is the file whose contents become the brief text (read via fs.readFileSync). Missing either, there is nothing deterministic to write.","triggerScenarios":"The script is run as 'surface-brief.mjs write <target>' with bodyFile omitted, or 'surface-brief.mjs write' with neither. argv destructuring puts argv[2] in target and argv[3] in bodyFile; the guard is !target || !bodyFile.","commonSituations":"User forgets the body file argument expecting an editor to open; passes only the target; the body path variable was unset in a wrapper; misread the usage line and supplied related-targets before the body file.","solutions":["Supply both: 'surface-brief.mjs write src/components/Header.jsx ./brief.md'.","Create the body file first (e.g. echo, $EDITOR) so readFileSync succeeds.","Re-read the usage message: write <primary-target> <body-file> [related-target ...]."],"exampleFix":"# before\nnode surface-brief.mjs write src/components/Header.jsx\n# after\nnode surface-brief.mjs write src/components/Header.jsx ./header-brief.md","handlingStrategy":"validation","validationCode":"if (command === 'write' && (!target || !bodyFile)) {\n  throw new Error('write needs both <primary-target> and <body-file>');\n}\nif (!fs.existsSync(bodyFile)) throw new Error('body file not found: ' + bodyFile);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check bodyFile existence before invoking so the error message points at the right cause.","Keep a brief body template handy so 'write' always has a non-empty body file.","Pin argument order in wrapper scripts: target first, body second."],"tags":["cli","surface-brief","argument-parsing","write"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}