What causes "usage: surface-brief.mjs write " in pbakaus/impeccable?

Supply both arguments: `surface-brief.mjs write src/App.tsx ./brief.md`.

pbakaus/impeccable · error · Error

usage: surface-brief.mjs write <primary-target> <body-file>

Error message

usage: surface-brief.mjs write <primary-target> <body-file>

What it means

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.

Source

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

    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>');
    const filePath = writeSurfaceBrief({
      projectRoot,
      primaryTarget: target,
      relatedTargets,
      body: fs.readFileSync(bodyFile, 'utf-8'),
    });
    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
    return;
  }
  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');
}

function isMainModule() {
  if (!process.argv[1]) return false;
  try {
    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);
  } catch {
    return import.meta.url === pathToFileURL(process.argv[1]).href;

View on GitHub (pinned to d14711ae3d)

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.

Example fix

# before
node surface-brief.mjs write src/App.tsx

# after
node surface-brief.mjs write src/App.tsx ./brief.md

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

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

Try / catch

if (!canWriteBrief(target, bodyFile)) {
  console.error('usage: surface-brief.mjs write <primary-target> <body-file>');
  process.exit(2);
}

Prevention

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.

When it happens

Trigger: Running `surface-brief.mjs write <target>` without a body file, or `surface-brief.mjs write` with neither argument.

Common situations: Forgot the body file argument, or a wrapper script passed an undefined body path.

Related errors

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