What causes "usage: surface-brief.mjs [target] [body-file] [related-target ...]" in pbakaus/impeccable?

Use one of the four subcommands: path, list, read, or write.

usage: surface-brief.mjs <path|list|read|write> [target] [bo

Error message

usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]

What it means

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.

Source

Thrown at skill/scripts/surface-brief.mjs:55

    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;
  }
}

if (isMainModule()) {
  try {
    main(process.argv.slice(2));
  } catch (error) {
    process.stderr.write(`${error?.message || error}\n`);
    process.exit(1);
  }

View on GitHub (pinned to d14711ae3d)

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.

Example fix

# before
node surface-brief.mjs create src/components/Header.jsx
# after
node surface-brief.mjs write src/components/Header.jsx ./brief.md

Defensive patterns

Strategy: validation

Validate before calling

const COMMANDS = new Set(['path', 'list', 'read', 'write']);
if (!COMMANDS.has(command)) {
  console.error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] ...');
  process.exit(2);
}

Prevention

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.

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

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