{"record":{"id":"6c70088304579184","repo":"pbakaus/impeccable","slug":"surface-brief-path-requires-a-concrete-target","errorCode":null,"errorMessage":"surface brief path requires a concrete target","messagePattern":"surface brief path requires a concrete target","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"plugin/skills/impeccable/scripts/surface-brief.mjs","lineNumber":27,"sourceCode":"  surfaceBriefPathForTarget,\n  writeSurfaceBrief,\n} from './lib/surface-briefs.mjs';\n\nfunction summary(brief, projectRoot) {\n  return {\n    slug: brief.slug,\n    path: path.relative(projectRoot, brief.path).split(path.sep).join('/'),\n    primaryTarget: brief.primaryTarget,\n    relatedTargets: brief.relatedTargets,\n  };\n}\n\nfunction main(argv) {\n  const [command, target, bodyFile, ...relatedTargets] = argv;\n  const projectRoot = resolveProjectRoot(process.cwd(), target ? { targetPath: target } : {});\n  if (command === 'path') {\n    const filePath = surfaceBriefPathForTarget(target, { projectRoot });\n    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>');","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/pbakaus/impeccable/blob/d14711ae3d1a1dd62dee61a358d27f107c51ccd0/plugin/skills/impeccable/scripts/surface-brief.mjs#L9-L45","documentation":"Thrown by surface-brief.mjs main when the `path` command is run without a concrete target, i.e. surfaceBriefPathForTarget returned null. The path command needs a specific target to compute the brief file location, since without one there is no deterministic path to print.","triggerScenarios":"Running `surface-brief.mjs path` with no second argument, or with a target that does not resolve to a concrete file path.","commonSituations":"Forgetting the target argument, or passing a directory/alias that surfaceBriefPathForTarget cannot map to a path.","solutions":["Provide a concrete target: `surface-brief.mjs path src/components/Header.tsx`.","Use `list` or `read` if you want to discover existing briefs without a specific target.","Confirm the target path resolves inside the project root."],"exampleFix":"# before\nnode surface-brief.mjs path\n\n# after\nnode surface-brief.mjs path src/components/Header.tsx","handlingStrategy":"validation","validationCode":"function hasConcreteTarget(target) {\n  return typeof target === 'string' && target.length > 0;\n}","typeGuard":"function isConcreteTarget(target) {\n  return typeof target === 'string' && target.trim().length > 0;\n}","tryCatchPattern":"if (!isConcreteTarget(target)) {\n  console.error('pass a target file, or use `list` to discover briefs');\n  process.exit(2);\n}","preventionTips":["Require the target argument for the `path` command in wrapper scripts.","Offer `list` as the zero-arg discovery command.","Validate argv length before dispatching to commands."],"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"}