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

Pass a concrete target: `impeccable surface-brief path `.

surface brief path requires a concrete target

Error message

surface brief path requires a concrete target

What it means

`impeccable surface-brief path` requires a concrete target; when no target resolves to an actual brief file, the command prints this usage error and exits 1. `surface_brief_path_for_target` returned None, so there is no file path to print.

Source

Thrown at crates/context/src/surface_brief_cli.rs:40

    let env = io.env.clone();
    let command = args.first().map(String::as_str);
    let target = args.get(1).map(String::as_str).filter(|s| !s.is_empty());
    let body_file = args.get(2).map(String::as_str).filter(|s| !s.is_empty());
    let related: Vec<String> = if args.len() > 3 { args[3..].to_vec() } else { vec![] };
    let opts = TargetOptions { target_path: target.map(|t| t.to_string()) };
    let project_root = resolve_project_root(&cwd, &opts, &env);
    let rel_out = |p: &str| -> String {
        let r = jsp::relative(&cwd, &cwd, p);
        if r.is_empty() {
            p.to_string()
        } else {
            r
        }
    };
    match command {
        Some("path") => {
            let Some(fp) = surface_brief_path_for_target(target, &project_root) else {
                io.err("surface brief path requires a concrete target\n");
                return 1;
            };
            io.out(&format!("{}\n", rel_out(&fp)));
            0
        }
        Some("list") => {
            let rows: Vec<Value> = list_surface_briefs(&project_root).iter().map(|b| summary(b, &project_root)).collect();
            io.out(&format!("{}\n", json_pretty(&Value::Array(rows))));
            0
        }
        Some("read") => {
            let result = resolve_surface_brief(&project_root, target);
            if let Some(b) = result.brief {
                io.out(&b.text);
                return 0;
            }
            if !result.candidates.is_empty() {
                let rows: Vec<Value> = result.candidates.iter().map(|b| summary(b, &project_root)).collect();

View on GitHub (pinned to 2bc2879276)

Solutions

Pass a concrete target: `impeccable surface-brief path <target>`.
Run `impeccable surface-brief list` to see targets that have briefs.
Generate a brief first via `surface-brief write` before asking for its path.
Check target spelling/case against the project's known targets.

Example fix

// before
impeccable surface-brief path
// after
impeccable surface-brief path src/components/App.tsx

Defensive patterns

Strategy: validation

Validate before calling

if (!process.argv[3]) {
  console.error('surface-brief path requires a concrete target');
  process.exit(2);
}

Try / catch

const r = run('impeccable surface-brief path ' + target);
if (r.code === 1 && /requires a concrete target/.test(r.stderr)) {
  run('impeccable surface-brief list'); // pick a valid target
}

Prevention

Always pass an explicit target to `surface-brief path`.
Confirm the brief exists with `surface-brief list` first.
Run `surface-brief write` before querying its path.
Quote target paths to avoid shell splitting.

When it happens

Trigger: Running `surface-brief path` with no target argument, or with a target for which no surface brief file exists in the project (surface_brief_path_for_target fails).

Common situations: Forgetting the target argument, misspelling a target name, or asking for a path before any brief has been generated for that target.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/4b5f4e393b6fe84d. Report an issue: GitHub.