{"record":{"id":"d166b05f1e702da2","repo":"pbakaus/impeccable","slug":"error-d166b0","errorCode":null,"errorMessage":"{}\n","messagePattern":"\\{\\}\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/context/src/surface_brief_cli.rs","lineNumber":59,"sourceCode":"                return 1;\n            };\n            io.out(&format!(\"{}\\n\", rel_out(&fp)));\n            0\n        }\n        Some(\"list\") => {\n            let rows: Vec<Value> = list_surface_briefs(&project_root).iter().map(|b| summary(b, &project_root)).collect();\n            io.out(&format!(\"{}\\n\", json_pretty(&Value::Array(rows))));\n            0\n        }\n        Some(\"read\") => {\n            let result = resolve_surface_brief(&project_root, target);\n            if let Some(b) = result.brief {\n                io.out(&b.text);\n                return 0;\n            }\n            if !result.candidates.is_empty() {\n                let rows: Vec<Value> = result.candidates.iter().map(|b| summary(b, &project_root)).collect();\n                io.err(&format!(\"{}\\n\", json_pretty(&Value::Array(rows))));\n            }\n            2\n        }\n        Some(\"write\") => {\n            let (Some(t), Some(bf)) = (target, body_file) else {\n                io.err(\"usage: impeccable surface-brief write <primary-target> <body-file>\\n\");\n                return 1;\n            };\n            let body = match std::fs::read(bf) {\n                Ok(b) => String::from_utf8_lossy(&b).into_owned(),\n                Err(e) => {\n                    io.err(&format!(\"{}\\n\", node_read_error(bf, &e)));\n                    return 1;\n                }\n            };\n            match write_surface_brief(&project_root, t, &related, &body) {\n                Ok(fp) => {\n                    io.out(&format!(\"{}\\n\", rel_out(&fp)));","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/surface_brief_cli.rs#L41-L77","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Ambiguous short target names matching several files, targets referenced by path vs name inconsistently, or typos that still fuzzy-match several entries.","solutions":["Read the candidates JSON on stderr and rerun with the exact target you meant.","Pass a more specific target path to disambiguate.","Treat exit code 2 as 'disambiguate', not 'crash'; script callers should branch on it.","Use `surface-brief list` first to confirm the canonical target name."],"exampleFix":"// before\nimpeccable surface-brief read Button\n// after\nimpeccable surface-brief read src/components/Button.tsx","handlingStrategy":"fallback","validationCode":"// check the target is unambiguous before reading\nconst list = JSON.parse(run('impeccable surface-brief list --json').stdout);\nconst hits = list.filter(t => t.target === target);\nif (hits.length !== 1) throw new Error(`ambiguous target: ${target}`);","typeGuard":null,"tryCatchPattern":"const r = run(`impeccable surface-brief read ${target}`);\nif (r.code === 2) {\n  const candidates = JSON.parse(r.stderr);\n  return readBrief(candidates[0]); // disambiguate\n}","preventionTips":["Use full relative file paths as targets, not short names.","Resolve ambiguity via the stderr candidates JSON when exit code is 2.","Keep target naming consistent across scripts.","Run `surface-brief list` when unsure of canonical names."],"tags":["cli","ambiguity","disambiguation"],"backgroundTag":"entity-not-found","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}