{"record":{"id":"a0d01c3f58deb704","repo":"pbakaus/impeccable","slug":"usage-surface-brief-mjs-write-primary-target-b","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":"Error","httpStatus":null,"severity":"error","filePath":"plugin/skills/impeccable/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/plugin/skills/impeccable/scripts/surface-brief.mjs#L27-L63","documentation":"Thrown by surface-brief.mjs main when the `write` command is missing the primary target or the body file argument. Writing a brief requires both a target to anchor it and a file whose contents become the brief body.","triggerScenarios":"Running `surface-brief.mjs write <target>` without a body file, or `surface-brief.mjs write` with neither argument.","commonSituations":"Forgot the body file argument, or a wrapper script passed an undefined body path.","solutions":["Supply both arguments: `surface-brief.mjs write src/App.tsx ./brief.md`.","Ensure the body file exists and is readable before invoking write.","Generate the body to a temp file first if producing it programmatically."],"exampleFix":"# before\nnode surface-brief.mjs write src/App.tsx\n\n# after\nnode surface-brief.mjs write src/App.tsx ./brief.md","handlingStrategy":"validation","validationCode":"function canWriteBrief(target, bodyFile) {\n  return typeof target === 'string' && target.length > 0 && typeof bodyFile === 'string' && bodyFile.length > 0;\n}","typeGuard":"function isWriteArgs(args) {\n  return typeof args.target === 'string' && args.target.length > 0 && typeof args.bodyFile === 'string' && args.bodyFile.length > 0;\n}","tryCatchPattern":"if (!canWriteBrief(target, bodyFile)) {\n  console.error('usage: surface-brief.mjs write <primary-target> <body-file>');\n  process.exit(2);\n}","preventionTips":["Check argv length in automation before calling write.","Generate the body file first and pass its path explicitly.","Document the required argument order next to any wrapper invoking write."],"tags":["cli","surface-brief","validation"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}