{"record":{"id":"1e8648c257e87ce3","repo":"pbakaus/impeccable","slug":"usage-impeccable-surface-brief-write-primary-tar","errorCode":null,"errorMessage":"usage: impeccable surface-brief write <primary-target> <body-file>\n","messagePattern":"usage: impeccable surface-brief write <primary-target> <body-file>\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/surface_brief_cli.rs","lineNumber":65,"sourceCode":"            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)));\n                    0\n                }\n                Err(msg) => {\n                    io.err(&format!(\"{}\\n\", msg));\n                    1\n                }","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/surface_brief_cli.rs#L47-L83","documentation":"`surface-brief write` was called without both required arguments (primary target and body file); the command prints this usage line and exits 1. It is a pure argument-shape check via the `(Some(t), Some(bf))` pattern before any I/O.","triggerScenarios":"`impeccable surface-brief write` with zero or one of the two required positional arguments (<primary-target>, <body-file>).","commonSituations":"Omitting the body file because the brief body was meant to come from stdin (not supported), forgetting arguments in scripted invocations, or argument-order mistakes.","solutions":["Supply both arguments: `impeccable surface-brief write <primary-target> <body-file>`.","Write the brief body to a temp file first, then pass its path.","Check scripted calls pass arguments after flags correctly.","See the usage line printed by the command for the exact form."],"exampleFix":"// before\nimpeccable surface-brief write src/App.tsx\n// after\nimpeccable surface-brief write src/App.tsx /tmp/brief-body.md","handlingStrategy":"validation","validationCode":"const args = ['write', target, bodyFile];\nif (args.slice(1).some(a => !a)) throw new Error('usage: impeccable surface-brief write <primary-target> <body-file>');","typeGuard":null,"tryCatchPattern":"const r = run(`impeccable surface-brief write ${target} ${bodyFile}`);\nif (r.code === 1 && r.stderr.startsWith('usage: impeccable surface-brief write')) {\n  console.error('missing target or body-file argument');\n}","preventionTips":["Always pass both <primary-target> and <body-file> positionally.","Write the body to a file first; the command does not read stdin.","In scripts, assert argument count before spawning the CLI.","Remember flags come before positionals for other verbs; keep order fixed here."],"tags":["cli","usage","missing-argument"],"backgroundTag":"missing-cli-argument","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"}