Skip to content

Error messages lack next-step recovery guidance — define a style and audit failure paths #92

@JRS1986

Description

@JRS1986

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

  1. Define an error-message style: one line cause, one line next concrete action, one optional link to wiki.
  2. Add a src/coding_scaffold/errors.py with helpers (fail_with(cause, next_step, link=None)) that all CLI handlers use.
  3. Audit every raise SystemExit, print(\"error: ...\"), and silent-exit branch in cli.py and submodules.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions