{"record":{"id":"a8f2caa0efe7cf67","repo":"pbakaus/impeccable","slug":"usage-impeccable-surface-brief-path-list-read-wr","errorCode":null,"errorMessage":"usage: impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]\n","messagePattern":"usage: impeccable surface-brief <path\\|list\\|read\\|write> \\[target\\] \\[body-file\\] \\[related-target \\.\\.\\.\\]\n","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/context/src/surface_brief_cli.rs","lineNumber":87,"sourceCode":"                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                }\n            }\n        }\n        _ => {\n            io.err(\"usage: impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]\\n\");\n            1\n        }\n    }\n}\n","sourceCodeStart":69,"sourceCodeEnd":92,"githubUrl":"https://github.com/pbakaus/impeccable/blob/2bc2879276c1f321a53c4ca99d3371e411329b52/crates/context/src/surface_brief_cli.rs#L69-L92","documentation":"The `impeccable surface-brief` subcommand prints this usage line to stderr and exits with code 1 when it is invoked without a recognized sub-action as the first argument. The sub-command supports only `path`, `list`, `read`, and `write` actions, so any other (or missing) first argument falls into the catch-all `_` arm of the argument match. It tells the developer the correct command shape so they can retry.","triggerScenarios":"Running `impeccable surface-brief` with no arguments at all, or with a first argument that is not one of path|list|read|write (e.g. `impeccable surface-brief show mypage.html` or a typo like `impeccable surface-brief pat file.html`).","commonSituations":"Typos in the sub-action name; forgetting the action verb entirely and passing only a target path; copying syntax from other sub-commands (e.g. `detect`) that take a path directly; scripting errors where a variable holding the action is empty.","solutions":["Run `impeccable surface-brief <path|list|read|write> [target] [body-file] [related-target ...]` with a valid action: e.g. `impeccable surface-brief list`, `impeccable surface-brief read src/index.html`, or `impeccable surface-brief write src/index.html brief.md related.html`.","If you only meant to scan a file, use `impeccable detect <path>` instead — surface-brief manages stored briefs, not scanning.","Check shell scripts for an empty/unset variable holding the action word."],"exampleFix":"// before\nimpeccable surface-brief src/index.html   # missing action\n// after\nimpeccable surface-brief read src/index.html","handlingStrategy":"validation","validationCode":"const VALID = new Set([\"path\", \"list\", \"read\", \"write\"]);\nconst [action] = process.argv.slice(2);\nif (!VALID.has(action)) {\n  console.error(`surface-brief: action must be one of ${[...VALID].join(\"|\")}`);\n  process.exit(1);\n}","typeGuard":"const isSurfaceBriefAction = (a) => [\"path\",\"list\",\"read\",\"write\"].includes(a);","tryCatchPattern":"const r = spawnSync(\"impeccable\", [\"surface-brief\", action, target]);\nif (r.status !== 0 && /usage: impeccable surface-brief/.test(r.stderr.toString())) {\n  console.error(\"Invalid surface-brief action:\", action);\n}","preventionTips":["Wrap surface-brief calls in a script that whitelists the four actions","Never interpolate an unset shell variable as the action word","Check `impeccable surface-brief --help` after upgrades for new actions"],"tags":["cli","usage","argument-parsing"],"backgroundTag":"missing-required-argument","analyzedSha":"2bc2879276c1f321a53c4ca99d3371e411329b52","analyzedAt":"2026-09-08T04:51:14.109Z","contentChangedAt":"2026-09-08T04:51:14.109Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}