Summary
Review Castle's operator-facing errors and warnings for directness, consistency, and useful recovery guidance. Keep the diagnostic detail an operator needs, but remove internal design explanations and repeated context.
This complements #15. That issue owns structured failures and command exit status; this issue owns the text shown to operators.
Problem
Several messages are substantially longer than the failure they describe:
lib/castle/commands.ex: the synthesised-record refusal, root-mismatch errors, unknown-release refusal, and restart-marker failures explain implementation history or multiple internal states before saying what the operator should do.
lib/castle/peer.ex: security and filesystem errors include long explanations that obscure the failed operation and recovery action.
lib/castle.ex: the missing-release-archive warning could lead with the missing archive and the action to take.
The ordinary operation errors are also inconsistent. Unpack, install, commit, and remove failures use different sentence shapes and punctuation, and file errors are not always rendered as human-readable filesystem errors.
Representative locations on release/1.0.0 include:
lib/castle/commands.ex:238, :263, :395, :518, :817, :1204-1277, :1442, and :1462
lib/castle/peer.ex:531, :829, and :1097
lib/castle.ex:125
Line numbers are pointers, not an exhaustive inventory.
Direction
- State the failed condition first.
- Follow with impact or recovery only when it helps the operator act.
- Remove implementation history, defensive justification, and false contrasts.
- Qualify ambiguous paths such as
RELEASES with the relevant release directory.
- Use a consistent shape for operation failures, such as
Cannot <verb> <target>: <reason>.
- Render filesystem reason atoms with
:file.format_error/1; retain inspect/1 for structured OTP terms.
- Preserve identifiers, paths, versions, and security-relevant facts needed to diagnose the failure.
Acceptance criteria
- The identified Castle errors and warnings are shorter and use consistent terminology.
- Restart-marker and release-root refusals explain the condition and next action without narrating Castle's internal design.
- File failures use human-readable filesystem reasons where applicable.
- Tests assert the revised messages where exact output is part of the contract.
- Command results, exit status, and release-management behavior do not change as part of this issue.
RELEASE.md records the user-visible diagnostic cleanup.
Summary
Review Castle's operator-facing errors and warnings for directness, consistency, and useful recovery guidance. Keep the diagnostic detail an operator needs, but remove internal design explanations and repeated context.
This complements #15. That issue owns structured failures and command exit status; this issue owns the text shown to operators.
Problem
Several messages are substantially longer than the failure they describe:
lib/castle/commands.ex: the synthesised-record refusal, root-mismatch errors, unknown-release refusal, and restart-marker failures explain implementation history or multiple internal states before saying what the operator should do.lib/castle/peer.ex: security and filesystem errors include long explanations that obscure the failed operation and recovery action.lib/castle.ex: the missing-release-archive warning could lead with the missing archive and the action to take.The ordinary operation errors are also inconsistent. Unpack, install, commit, and remove failures use different sentence shapes and punctuation, and file errors are not always rendered as human-readable filesystem errors.
Representative locations on
release/1.0.0include:lib/castle/commands.ex:238,:263,:395,:518,:817,:1204-1277,:1442, and:1462lib/castle/peer.ex:531,:829, and:1097lib/castle.ex:125Line numbers are pointers, not an exhaustive inventory.
Direction
RELEASESwith the relevant release directory.Cannot <verb> <target>: <reason>.:file.format_error/1; retaininspect/1for structured OTP terms.Acceptance criteria
RELEASE.mdrecords the user-visible diagnostic cleanup.