UAT: TUI help panel key bindings are inconsistent with actual app bindings #1290

Open
opened 2026-04-02 09:00:17 +00:00 by freemo · 4 comments
Owner

Bug Report: [tui] — Help panel key bindings are inconsistent with actual app bindings

Severity Assessment

  • Impact: Users following the help panel documentation will press tab or ctrl+tab expecting persona/preset cycling, but these keys are not bound to those actions. The actual ctrl+t binding is not documented in the help panel, creating a confusing and misleading user experience.
  • Likelihood: High. Any user who opens the help panel (F1) and attempts to use the documented key bindings will encounter this discrepancy.
  • Priority: Medium

Location

  • File 1: src/cleveragents/tui/widgets/help_panel_overlay.py — lines 35–36
  • File 2: src/cleveragents/tui/app.py — lines 90–93

Description

During UAT testing of the TUI components, a discrepancy was found between the key bindings documented in the help panel overlay and the actual key bindings registered in the TUI app.

The help panel (_CONTEXT_ITEMS["Main Screen"]) documents:

  • tab → "Cycle to next persona"
  • ctrl+tab → "Cycle to next argument preset"

However, the app's BINDINGS class variable only registers:

  • ctrl+q → quit
  • f1 → help
  • ctrl+t → cycle_preset

Neither tab nor ctrl+tab are registered as bindings. The ctrl+t preset-cycling binding is not documented in the help panel at all.

Evidence

Help panel overlay (src/cleveragents/tui/widgets/help_panel_overlay.py, lines 35–36):

("tab", "Cycle to next persona"),
("ctrl+tab", "Cycle to next argument preset"),

App BINDINGS (src/cleveragents/tui/app.py, lines 90–93):

BINDINGS: ClassVar[list[tuple[str, str, str]]] = [
    ("ctrl+q", "quit", "Quit"),
    ("f1", "help", "Help"),
    ("ctrl+t", "cycle_preset", "Cycle Preset"),
]

Steps to Reproduce

  1. Run the TUI app
  2. Press F1 to open the help panel
  3. The help panel shows tab for "Cycle to next persona" and ctrl+tab for "Cycle to next argument preset"
  4. Press tab — no persona cycling occurs
  5. Press ctrl+tab — no preset cycling occurs
  6. Press ctrl+t — preset cycling occurs (but this is not documented in the help panel)

Expected Behavior

The key bindings shown in the help panel should match the key bindings registered in the app. Either:

  1. Update BINDINGS in app.py to include tab for persona cycling and ctrl+tab for preset cycling (aligning the app to the help panel documentation), OR
  2. Update help_panel_overlay.py to show ctrl+t for preset cycling and remove the undocumented tab binding (aligning the help panel to the app)

Actual Behavior

The help panel documents tab and ctrl+tab bindings that do not exist in the app, and the ctrl+t binding that does exist is absent from the help panel.

Category

tui / uat


Metadata

  • Branch: fix/tui-help-panel-key-binding-inconsistency
  • Commit Message: fix(tui): align help panel key bindings with registered app BINDINGS
  • Milestone: v3.7.0
  • Parent Epic: #868

Subtasks

  • Determine the correct resolution with the team: update BINDINGS to match the help panel, or update the help panel to match BINDINGS
  • Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail that asserts every key binding shown in the help panel's _CONTEXT_ITEMS["Main Screen"] has a corresponding entry in the app's BINDINGS
  • Write a TDD issue-capture Behave scenario tagged @tdd_issue, @tdd_expected_fail that asserts every key binding in the app's BINDINGS is documented in the help panel's _CONTEXT_ITEMS["Main Screen"]
  • Apply the chosen fix: either add tab (persona cycling) and ctrl+tab (preset cycling) to BINDINGS in app.py, or update _CONTEXT_ITEMS["Main Screen"] in help_panel_overlay.py to reflect ctrl+t and remove the phantom tab entry
  • Remove @tdd_expected_fail tags from both TDD scenarios once the fix is in place and verify they pass
  • Run nox -e typecheck to confirm no type regressions
  • Run nox -e unit_tests to confirm all Behave tests pass
  • Run nox -e coverage_report to confirm coverage remains ≥ 97%
  • Run nox (all default sessions) and fix any errors

Definition of Done

  • Both @tdd_expected_fail TDD capture scenarios are committed first and demonstrate the binding mismatch
  • The help panel _CONTEXT_ITEMS["Main Screen"] and the app BINDINGS are fully consistent — every documented binding is registered, and every registered binding is documented
  • Both TDD scenarios pass without @tdd_expected_fail after the fix
  • No regressions in existing TUI tests
  • All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests, nox -e coverage_report)
  • Coverage >= 97%
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Bug Report: [tui] — Help panel key bindings are inconsistent with actual app bindings ### Severity Assessment - **Impact**: Users following the help panel documentation will press `tab` or `ctrl+tab` expecting persona/preset cycling, but these keys are not bound to those actions. The actual `ctrl+t` binding is not documented in the help panel, creating a confusing and misleading user experience. - **Likelihood**: High. Any user who opens the help panel (F1) and attempts to use the documented key bindings will encounter this discrepancy. - **Priority**: Medium ### Location - **File 1**: `src/cleveragents/tui/widgets/help_panel_overlay.py` — lines 35–36 - **File 2**: `src/cleveragents/tui/app.py` — lines 90–93 ### Description During UAT testing of the TUI components, a discrepancy was found between the key bindings documented in the help panel overlay and the actual key bindings registered in the TUI app. The help panel (`_CONTEXT_ITEMS["Main Screen"]`) documents: - `tab` → "Cycle to next persona" - `ctrl+tab` → "Cycle to next argument preset" However, the app's `BINDINGS` class variable only registers: - `ctrl+q` → quit - `f1` → help - `ctrl+t` → cycle_preset Neither `tab` nor `ctrl+tab` are registered as bindings. The `ctrl+t` preset-cycling binding is not documented in the help panel at all. ### Evidence **Help panel overlay** (`src/cleveragents/tui/widgets/help_panel_overlay.py`, lines 35–36): ```python ("tab", "Cycle to next persona"), ("ctrl+tab", "Cycle to next argument preset"), ``` **App BINDINGS** (`src/cleveragents/tui/app.py`, lines 90–93): ```python BINDINGS: ClassVar[list[tuple[str, str, str]]] = [ ("ctrl+q", "quit", "Quit"), ("f1", "help", "Help"), ("ctrl+t", "cycle_preset", "Cycle Preset"), ] ``` ### Steps to Reproduce 1. Run the TUI app 2. Press `F1` to open the help panel 3. The help panel shows `tab` for "Cycle to next persona" and `ctrl+tab` for "Cycle to next argument preset" 4. Press `tab` — no persona cycling occurs 5. Press `ctrl+tab` — no preset cycling occurs 6. Press `ctrl+t` — preset cycling occurs (but this is not documented in the help panel) ### Expected Behavior The key bindings shown in the help panel should match the key bindings registered in the app. Either: 1. Update `BINDINGS` in `app.py` to include `tab` for persona cycling and `ctrl+tab` for preset cycling (aligning the app to the help panel documentation), **OR** 2. Update `help_panel_overlay.py` to show `ctrl+t` for preset cycling and remove the undocumented `tab` binding (aligning the help panel to the app) ### Actual Behavior The help panel documents `tab` and `ctrl+tab` bindings that do not exist in the app, and the `ctrl+t` binding that does exist is absent from the help panel. ### Category tui / uat --- ## Metadata - **Branch**: `fix/tui-help-panel-key-binding-inconsistency` - **Commit Message**: `fix(tui): align help panel key bindings with registered app BINDINGS` - **Milestone**: v3.7.0 - **Parent Epic**: #868 ## Subtasks - [ ] Determine the correct resolution with the team: update `BINDINGS` to match the help panel, or update the help panel to match `BINDINGS` - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` that asserts every key binding shown in the help panel's `_CONTEXT_ITEMS["Main Screen"]` has a corresponding entry in the app's `BINDINGS` - [ ] Write a TDD issue-capture Behave scenario tagged `@tdd_issue`, `@tdd_expected_fail` that asserts every key binding in the app's `BINDINGS` is documented in the help panel's `_CONTEXT_ITEMS["Main Screen"]` - [ ] Apply the chosen fix: either add `tab` (persona cycling) and `ctrl+tab` (preset cycling) to `BINDINGS` in `app.py`, or update `_CONTEXT_ITEMS["Main Screen"]` in `help_panel_overlay.py` to reflect `ctrl+t` and remove the phantom `tab` entry - [ ] Remove `@tdd_expected_fail` tags from both TDD scenarios once the fix is in place and verify they pass - [ ] Run `nox -e typecheck` to confirm no type regressions - [ ] Run `nox -e unit_tests` to confirm all Behave tests pass - [ ] Run `nox -e coverage_report` to confirm coverage remains ≥ 97% - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done - [ ] Both `@tdd_expected_fail` TDD capture scenarios are committed first and demonstrate the binding mismatch - [ ] The help panel `_CONTEXT_ITEMS["Main Screen"]` and the app `BINDINGS` are fully consistent — every documented binding is registered, and every registered binding is documented - [ ] Both TDD scenarios pass without `@tdd_expected_fail` after the fix - [ ] No regressions in existing TUI tests - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`, `nox -e coverage_report`) - [ ] Coverage >= 97% - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.7.0 milestone 2026-04-02 09:00:34 +00:00
Author
Owner

This issue is a child of Epic #868 (TUI Interface, Modals and Persona System) and should be tracked under that Epic.

Dependency relationship: #1290 (this issue) is a child of #868 (parent Epic). Per CONTRIBUTING.md conventions, the child issue blocks the parent Epic — the Epic cannot be considered complete until this bug is resolved.

Blocking status: This issue is not blocking any currently open issue. It is an independent bug discovery from UAT testing (reported by uat-tester-2) and can be worked on at any time within the v3.7.0 milestone scope.

This issue is a child of Epic #868 (TUI Interface, Modals and Persona System) and should be tracked under that Epic. **Dependency relationship**: #1290 (this issue) is a child of #868 (parent Epic). Per CONTRIBUTING.md conventions, the child issue blocks the parent Epic — the Epic cannot be considered complete until this bug is resolved. **Blocking status**: This issue is **not blocking** any currently open issue. It is an independent bug discovery from UAT testing (reported by uat-tester-2) and can be worked on at any time within the v3.7.0 milestone scope.
freemo self-assigned this 2026-04-02 18:45:25 +00:00
Author
Owner

⚠️ Overlap with #1441 Detected

Issue #1441 (fix(tui): correct ctrl+tab preset-cycling binding) was created after this issue and covers the same root problem with a specific fix direction: change ctrl+tctrl+tab in BINDINGS.

Relationship:

  • This issue (#1290) is the broader parent — it covers ALL binding inconsistencies between the help panel and BINDINGS
  • #1441 is a specific, actionable child — it proposes the concrete fix for the preset-cycling binding

Recommendation: Link #1441 as a child of this issue. Once #1441 is resolved, update this issue to track only the remaining gap (persona cycling via tab — which is documented in the help panel but has no corresponding binding in the app).


Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

⚠️ **Overlap with #1441 Detected** Issue #1441 (fix(tui): correct ctrl+tab preset-cycling binding) was created after this issue and covers the same root problem with a specific fix direction: change `ctrl+t` → `ctrl+tab` in `BINDINGS`. **Relationship:** - This issue (#1290) is the broader parent — it covers ALL binding inconsistencies between the help panel and `BINDINGS` - #1441 is a specific, actionable child — it proposes the concrete fix for the preset-cycling binding **Recommendation:** Link #1441 as a child of this issue. Once #1441 is resolved, update this issue to track only the remaining gap (persona cycling via `tab` — which is documented in the help panel but has no corresponding binding in the app). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Author
Owner

MoSCoW classification: MoSCoW/Could Have

Priority classification: Priority/Low

Rationale: TUI help panel key bindings being inconsistent with actual app bindings is a documentation/display issue within the TUI. The actual key bindings work correctly — the help panel just shows incorrect information. This is a polish issue that improves user experience but doesn't affect functionality. Could Have.


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

MoSCoW classification: **MoSCoW/Could Have** Priority classification: **Priority/Low** Rationale: TUI help panel key bindings being inconsistent with actual app bindings is a documentation/display issue within the TUI. The actual key bindings work correctly — the help panel just shows incorrect information. This is a polish issue that improves user experience but doesn't affect functionality. Could Have. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Label compliance fix applied:

  • Added missing label: Type/Bug
  • Reason: Per CONTRIBUTING.md, every issue must have exactly one Type/* label. This UAT bug issue was inferred as Type/Bug.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Added missing label: `Type/Bug` - Reason: Per CONTRIBUTING.md, every issue must have exactly one `Type/*` label. This UAT bug issue was inferred as `Type/Bug`. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
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#1290
No description provided.