What causes "surface brief path requires a concrete target" in pbakaus/impeccable?

Provide a concrete target: `surface-brief.mjs path src/components/Header.tsx`.

pbakaus/impeccable · error · Error

surface brief path requires a concrete target

Error message

surface brief path requires a concrete target

What it means

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.

Source

Thrown at plugin/skills/impeccable/scripts/surface-brief.mjs:27

  surfaceBriefPathForTarget,
  writeSurfaceBrief,
} from './lib/surface-briefs.mjs';

function summary(brief, projectRoot) {
  return {
    slug: brief.slug,
    path: path.relative(projectRoot, brief.path).split(path.sep).join('/'),
    primaryTarget: brief.primaryTarget,
    relatedTargets: brief.relatedTargets,
  };
}

function main(argv) {
  const [command, target, bodyFile, ...relatedTargets] = argv;
  const projectRoot = resolveProjectRoot(process.cwd(), target ? { targetPath: target } : {});
  if (command === 'path') {
    const filePath = surfaceBriefPathForTarget(target, { projectRoot });
    if (!filePath) throw new Error('surface brief path requires a concrete target');
    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
    return;
  }
  if (command === 'list') {
    process.stdout.write(`${JSON.stringify(listSurfaceBriefs(projectRoot).map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
    return;
  }
  if (command === 'read') {
    const result = resolveSurfaceBrief(projectRoot, target || null);
    if (result.brief) {
      process.stdout.write(result.brief.text);
      return;
    }
    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
    process.exit(2);
  }
  if (command === 'write') {
    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');

View on GitHub (pinned to d14711ae3d)

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.

Example fix

# before
node surface-brief.mjs path

# after
node surface-brief.mjs path src/components/Header.tsx

Defensive patterns

Strategy: validation

Validate before calling

function hasConcreteTarget(target) {
  return typeof target === 'string' && target.length > 0;
}

Type guard

function isConcreteTarget(target) {
  return typeof target === 'string' && target.trim().length > 0;
}

Try / catch

if (!isConcreteTarget(target)) {
  console.error('pass a target file, or use `list` to discover briefs');
  process.exit(2);
}

Prevention

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.

When it happens

Trigger: Running `surface-brief.mjs path` with no second argument, or with a target that does not resolve to a concrete file path.

Common situations: Forgetting the target argument, or passing a directory/alias that surfaceBriefPathForTarget cannot map to a path.

Related errors

AI-assisted analysis of pbakaus/impeccable@d14711ae3d (2026-08-13). Data as JSON: /api/errors/6c70088304579184. Report an issue: GitHub.