{"record":{"id":"539710a911965fb2","repo":"pbakaus/impeccable","slug":"usage-surface-brief-mjs-path-list-read-write-t-539710","errorCode":null,"errorMessage":"usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]","messagePattern":"usage: surface-brief\\.mjs <path\\|list\\|read\\|write> \\[target\\] \\[body-file\\] \\[related-target \\.\\.\\.\\]","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"skill/scripts/surface-brief.mjs","lineNumber":55,"sourceCode":"    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;\n  }\n}\n\nif (isMainModule()) {\n  try {\n    main(process.argv.slice(2));\n  } catch (error) {\n    process.stderr.write(`${error?.message || error}\\n`);\n    process.exit(1);\n  }","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/skill/scripts/surface-brief.mjs#L37-L73","documentation":"Thrown by main() in surface-brief.mjs as the final fallthrough when the command (argv[1]) is not one of 'path', 'list', 'read', or 'write', or is undefined. It is the catch-all usage error printed to guide the caller to a valid subcommand. Each valid subcommand returns early; reaching the end means the command was unrecognized or missing.","triggerScenarios":"The script is run with no arguments (argv empty, command undefined), or with an unrecognized first token like 'surface-brief.mjs create', 'surface-brief.mjs update', or a typo like 'surface-brief.mjs wrte'.","commonSituations":"User runs the bare script expecting a menu; typo'd subcommand; outdated docs referenced a since-renamed command; wrapper script passed flags but no subcommand.","solutions":["Use one of the four subcommands: path, list, read, or write.","Run 'surface-brief.mjs list' first to inspect existing briefs.","Update any wrapper scripts or docs that referenced a removed/renamed subcommand."],"exampleFix":"# before\nnode surface-brief.mjs create src/components/Header.jsx\n# after\nnode surface-brief.mjs write src/components/Header.jsx ./brief.md","handlingStrategy":"validation","validationCode":"const COMMANDS = new Set(['path', 'list', 'read', 'write']);\nif (!COMMANDS.has(command)) {\n  console.error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] ...');\n  process.exit(2);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Print the usage line to stderr and exit(2) for a clean CLI contract.","Add a 'help' alias that prints the same usage.","Reject typos at the CLI shim so the underlying script never sees them."],"tags":["cli","surface-brief","argument-parsing","usage"],"backgroundTag":null,"analyzedSha":"d14711ae3d1a1dd62dee61a358d27f107c51ccd0","analyzedAt":"2026-08-13T00:52:25.771Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}