Problem
Failure paths in cli.py and its subcommands tend to print a terse error and exit non-zero. They rarely tell the user the concrete next step ("install the missing tool with X", "create the missing file with Y", "set the missing env var Z").
Examples observed:
setup run failing to detect a tool gives an exit code rather than "Tool X not found. Install with: `coding-scaffold setup tool --tool X --install`".
context lint on a repo without AGENTS.md or .coding-scaffold/ silently produces nothing useful.
credentials --format env writes a template; if the user leaves it empty, downstream commands do not warn.
eval run failures often do not point at which artifact failed or how to fix it.
Why it matters
Recovery friction is the difference between a tool a team adopts and one they abandon after the first surprise. Experienced devs expect actionable errors.
Proposed approach
- Define an error-message style: one line cause, one line next concrete action, one optional link to wiki.
- Add a
src/coding_scaffold/errors.py with helpers (fail_with(cause, next_step, link=None)) that all CLI handlers use.
- Audit every
raise SystemExit, print(\"error: ...\"), and silent-exit branch in cli.py and submodules.
- Add at least one test per command that exercises the no-config / missing-input path and asserts the next-step phrase is present.
Acceptance criteria
- Every CLI failure path either passes through the shared helper or has a passing "no-config recovery" test.
- Wiki has a short "Errors and recovery" page enumerating the recurring failure modes.
Problem
Failure paths in
cli.pyand its subcommands tend to print a terse error and exit non-zero. They rarely tell the user the concrete next step ("install the missing tool with X", "create the missing file with Y", "set the missing env var Z").Examples observed:
setup runfailing to detect a tool gives an exit code rather than "Tool X not found. Install with: `coding-scaffold setup tool --tool X --install`".context linton a repo withoutAGENTS.mdor.coding-scaffold/silently produces nothing useful.credentials --format envwrites a template; if the user leaves it empty, downstream commands do not warn.eval runfailures often do not point at which artifact failed or how to fix it.Why it matters
Recovery friction is the difference between a tool a team adopts and one they abandon after the first surprise. Experienced devs expect actionable errors.
Proposed approach
src/coding_scaffold/errors.pywith helpers (fail_with(cause, next_step, link=None)) that all CLI handlers use.raise SystemExit,print(\"error: ...\"), and silent-exit branch incli.pyand submodules.Acceptance criteria