Skip to content

docs(claude): add Error Messages four-ingredient strategy#1254

Merged
John-David Dalton (jdalton) merged 1 commit intomainfrom
jdd/claude-error-message-strategy
Apr 22, 2026
Merged

docs(claude): add Error Messages four-ingredient strategy#1254
John-David Dalton (jdalton) merged 1 commit intomainfrom
jdd/claude-error-message-strategy

Conversation

@jdalton
Copy link
Copy Markdown
Contributor

@jdalton John-David Dalton (jdalton) commented Apr 22, 2026

Summary

Adds an Error Messages section to CLAUDE.md with the four-ingredient strategy we're using across the fleet (copied from socket-repo-template):

  1. What — the rule that was violated (not the symptom)
  2. Where — the exact flag / file / key (never "somewhere in config")
  3. Saw vs. wanted — the offending value and the allowed shape
  4. Fix — one concrete action to resolve it

Plus rules on imperative voice, naming colliding records, and not silently auto-correcting.

Why

Right now socket-cli has a lot of errors like Invalid value for --limit: foo — true but not helpful. After this PR lands, the agent has a written rule to reach for so error messages are consistent and actionable.

What's NOT in this PR

Zero source-code changes. This is just the strategy doc. The actual error-message cleanup across src/ will land in follow-up PRs split by area (commands, dlx, utils, env, test, etc.) so each PR stays reviewable.

Test plan

  • Read the new section and make sure the examples feel right for socket-cli (some use InputError, one uses AuthError, each shows the 4 ingredients).
  • Nothing else to test — docs only, no code changes.

Note

Low Risk
Docs-only change to CLAUDE.md with no runtime or behavioral impact. Low risk aside from potentially influencing future error wording conventions.

Overview
Adds a new ### Error Messages section to CLAUDE.md that standardizes how CLI errors should be written using a four-part format (what/where/saw-vs-wanted/fix) and a few concrete rules (imperative voice, avoid vague “invalid”, name collisions explicitly, don’t silently auto-correct), with good/bad examples using InputError/AuthError.

Reviewed by Cursor Bugbot for commit 31b7466. Configure here.

Adds the four-ingredient error-message strategy (What / Where /
Saw vs. wanted / Fix) from socket-repo-template's CLAUDE.md.
Keeps the existing Error handling bullet (InputError/AuthError/
CResult) and adds a new Error Messages section underneath it.

Foundation for a series of follow-up PRs that fix socket-cli's
existing error messages to match this strategy. No source changes
in this PR — docs only.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants