pbakaus/impeccable · warning

{}

Error message

{}

What it means

The `surface-brief read` command found no brief but located candidate targets: it prints a JSON array of candidate summaries to stderr and exits with status 2. The `{}` message is the pretty-printed candidates list, signaling ambiguity rather than absence.

Source

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

                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();
                io.err(&format!("{}\n", json_pretty(&Value::Array(rows))));
            }
            2
        }
        Some("write") => {
            let (Some(t), Some(bf)) = (target, body_file) else {
                io.err("usage: impeccable surface-brief write <primary-target> <body-file>\n");
                return 1;
            };
            let body = match std::fs::read(bf) {
                Ok(b) => String::from_utf8_lossy(&b).into_owned(),
                Err(e) => {
                    io.err(&format!("{}\n", node_read_error(bf, &e)));
                    return 1;
                }
            };
            match write_surface_brief(&project_root, t, &related, &body) {
                Ok(fp) => {
                    io.out(&format!("{}\n", rel_out(&fp)));

View on GitHub (pinned to 2bc2879276)

Solutions

1. Read the candidates JSON on stderr and rerun with the exact target you meant.
2. Pass a more specific target path to disambiguate.
3. Treat exit code 2 as 'disambiguate', not 'crash'; script callers should branch on it.
4. Use `surface-brief list` first to confirm the canonical target name.

Example fix

// before
impeccable surface-brief read Button
// after
impeccable surface-brief read src/components/Button.tsx

// check the target is unambiguous before reading
const list = JSON.parse(run('impeccable surface-brief list --json').stdout);
const hits = list.filter(t => t.target === target);
if (hits.length !== 1) throw new Error(`ambiguous target: ${target}`);

const r = run(`impeccable surface-brief read ${target}`);
if (r.code === 2) {
  const candidates = JSON.parse(r.stderr);
  return readBrief(candidates[0]); // disambiguate
}

When it happens

Trigger: `surface-brief read <target>` where the exact brief was not found but result.candidates is non-empty — the target matched multiple/partial candidates, so the command disambiguates by dumping them.

Common situations: Ambiguous short target names matching several files, targets referenced by path vs name inconsistently, or typos that still fuzzy-match several entries.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• ambiguous snapshot slug; use an explicit ./path or remove th
• concept-seed: --candidate-count must be an integer from 5 to
• Unknown ignore-rule flag: ${arg}
• Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule
• overused-font is value-specific by default. Use ${IMPECCABLE

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