Refactor: Unify Error Handling and User Feedback in CLI #8857

Open
opened 2026-04-14 02:54:45 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Commit Message: refactor(cli): unify error handling and user feedback across CLI commands
  • Branch: refactor/cli-unify-error-handling-user-feedback

Background and Context

There are inconsistencies in how errors are handled and how feedback is provided to the user in the CLI commands. This can lead to a confusing and frustrating user experience.

Evidence:

  • Inconsistent Error Handling: In some cases, exceptions are caught and a user-friendly error message is printed to the console. In other cases, the exception is re-raised, which can result in a stack trace being displayed to the user.
  • Inconsistent User Feedback: The format and style of user feedback messages are inconsistent. Some messages are printed using rich.panel.Panel, while others are printed directly to the console. The use of colors and icons is also inconsistent.

Impacted Files:

  • src/cleveragents/cli/commands/plan.py
  • src/cleveragents/cli/commands/project.py
  • Other files in src/cleveragents/cli/commands/ may also be affected.

Recommended Remediation:

  • Establish a consistent error handling strategy for all CLI commands. All exceptions should be caught and a user-friendly error message should be displayed to the user. Stack traces should only be displayed when the --debug flag is used.
  • Create a centralized module for handling user feedback. This module should provide a consistent way to display messages, panels, tables, and other UI elements.
  • Refactor the existing CLI commands to use the new error handling and user feedback mechanisms.

Relevant Specification Sections:

  • ADR-021-cli-and-output-rendering.md

Expected Behavior

All CLI commands handle errors consistently: exceptions are caught, user-friendly messages are displayed, and stack traces are only shown when --debug is active. User feedback (messages, panels, tables) is rendered through a centralized module with a consistent style, color scheme, and iconography across all commands.

Acceptance Criteria

  • A consistent error handling strategy is defined and documented for all CLI commands.
  • All exceptions in CLI commands are caught and result in a user-friendly error message (no raw stack traces shown to the user by default).
  • Stack traces are only displayed when the --debug flag is passed.
  • A centralized user feedback module (e.g., src/cleveragents/cli/output.py or similar) is created.
  • The centralized module provides helpers for displaying messages, panels, tables, and other UI elements consistently.
  • src/cleveragents/cli/commands/plan.py is refactored to use the new error handling and feedback mechanisms.
  • src/cleveragents/cli/commands/project.py is refactored to use the new error handling and feedback mechanisms.
  • All other files in src/cleveragents/cli/commands/ are audited and refactored as needed.
  • All existing tests pass; new tests cover the centralized feedback module and error handling paths.
  • Test coverage >= 97%.

Subtasks

  • Audit all files in src/cleveragents/cli/commands/ for inconsistent error handling and feedback patterns.
  • Define and document the consistent error handling strategy (catch-all with --debug passthrough).
  • Create a centralized CLI output/feedback module with helpers for messages, panels, tables, and icons.
  • Refactor src/cleveragents/cli/commands/plan.py to use the new module.
  • Refactor src/cleveragents/cli/commands/project.py to use the new module.
  • Refactor all other affected CLI command files.
  • Write/update unit tests for the centralized feedback module.
  • Write/update tests for error handling paths (with and without --debug).
  • Verify all nox sessions pass with coverage >= 97%.

Definition of Done

This issue should be closed when:

  1. A centralized CLI output/feedback module exists and is used consistently across all CLI commands.
  2. All CLI commands catch exceptions and display user-friendly error messages; stack traces are gated behind --debug.
  3. All existing tests pass and new tests cover the new module and error handling paths.
  4. Test coverage is >= 97%.
  5. The implementation is consistent with ADR-021-cli-and-output-rendering.md.

Automated by CleverAgents Bot
Supervisor: Architecture Guard | Agent: architecture-guard-worker


Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(cli): unify error handling and user feedback across CLI commands` - **Branch**: `refactor/cli-unify-error-handling-user-feedback` ## Background and Context There are inconsistencies in how errors are handled and how feedback is provided to the user in the CLI commands. This can lead to a confusing and frustrating user experience. **Evidence:** * **Inconsistent Error Handling:** In some cases, exceptions are caught and a user-friendly error message is printed to the console. In other cases, the exception is re-raised, which can result in a stack trace being displayed to the user. * **Inconsistent User Feedback:** The format and style of user feedback messages are inconsistent. Some messages are printed using `rich.panel.Panel`, while others are printed directly to the console. The use of colors and icons is also inconsistent. **Impacted Files:** * `src/cleveragents/cli/commands/plan.py` * `src/cleveragents/cli/commands/project.py` * Other files in `src/cleveragents/cli/commands/` may also be affected. **Recommended Remediation:** * Establish a consistent error handling strategy for all CLI commands. All exceptions should be caught and a user-friendly error message should be displayed to the user. Stack traces should only be displayed when the `--debug` flag is used. * Create a centralized module for handling user feedback. This module should provide a consistent way to display messages, panels, tables, and other UI elements. * Refactor the existing CLI commands to use the new error handling and user feedback mechanisms. **Relevant Specification Sections:** * ADR-021-cli-and-output-rendering.md ## Expected Behavior All CLI commands handle errors consistently: exceptions are caught, user-friendly messages are displayed, and stack traces are only shown when `--debug` is active. User feedback (messages, panels, tables) is rendered through a centralized module with a consistent style, color scheme, and iconography across all commands. ## Acceptance Criteria - [ ] A consistent error handling strategy is defined and documented for all CLI commands. - [ ] All exceptions in CLI commands are caught and result in a user-friendly error message (no raw stack traces shown to the user by default). - [ ] Stack traces are only displayed when the `--debug` flag is passed. - [ ] A centralized user feedback module (e.g., `src/cleveragents/cli/output.py` or similar) is created. - [ ] The centralized module provides helpers for displaying messages, panels, tables, and other UI elements consistently. - [ ] `src/cleveragents/cli/commands/plan.py` is refactored to use the new error handling and feedback mechanisms. - [ ] `src/cleveragents/cli/commands/project.py` is refactored to use the new error handling and feedback mechanisms. - [ ] All other files in `src/cleveragents/cli/commands/` are audited and refactored as needed. - [ ] All existing tests pass; new tests cover the centralized feedback module and error handling paths. - [ ] Test coverage >= 97%. ## Subtasks - [ ] Audit all files in `src/cleveragents/cli/commands/` for inconsistent error handling and feedback patterns. - [ ] Define and document the consistent error handling strategy (catch-all with `--debug` passthrough). - [ ] Create a centralized CLI output/feedback module with helpers for messages, panels, tables, and icons. - [ ] Refactor `src/cleveragents/cli/commands/plan.py` to use the new module. - [ ] Refactor `src/cleveragents/cli/commands/project.py` to use the new module. - [ ] Refactor all other affected CLI command files. - [ ] Write/update unit tests for the centralized feedback module. - [ ] Write/update tests for error handling paths (with and without `--debug`). - [ ] Verify all `nox` sessions pass with coverage >= 97%. ## Definition of Done This issue should be closed when: 1. A centralized CLI output/feedback module exists and is used consistently across all CLI commands. 2. All CLI commands catch exceptions and display user-friendly error messages; stack traces are gated behind `--debug`. 3. All existing tests pass and new tests cover the new module and error handling paths. 4. Test coverage is >= 97%. 5. The implementation is consistent with ADR-021-cli-and-output-rendering.md. --- **Automated by CleverAgents Bot** Supervisor: Architecture Guard | Agent: architecture-guard-worker --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.6.0 milestone 2026-04-14 03:03:26 +00:00
Author
Owner

Triage Decision: VERIFIED — MoSCoW/Should Have

Valid refactoring request: inconsistent error handling and user feedback across CLI commands creates a confusing UX. A centralized output module would improve consistency and maintainability.

This is a Should Have improvement — important for user experience but not blocking core functionality. Assigning to v3.6.0 (Advanced Concepts & Deferred Features) as this is a quality-of-life improvement.

Priority/Medium — UX improvement, not a blocker.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage Decision: VERIFIED — MoSCoW/Should Have** Valid refactoring request: inconsistent error handling and user feedback across CLI commands creates a confusing UX. A centralized output module would improve consistency and maintainability. This is a Should Have improvement — important for user experience but not blocking core functionality. Assigning to v3.6.0 (Advanced Concepts & Deferred Features) as this is a quality-of-life improvement. **Priority/Medium** — UX improvement, not a blocker. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#8857
No description provided.