UAT: Help panel is context-sensitive but spec requires it to always show the same global shortcuts #1359

New issue

Open

opened 2026-04-02 16:58:20 +00:00 by freemo · 0 comments

freemo commented

2026-04-02 16:58:20 +00:00

Owner

Bug Report: [tui/help-panel] — Help panel is context-sensitive, violating spec requirement

Severity Assessment

Impact: Medium. Users pressing F1 in different input modes (slash command, reference picker, shell mode) will see different help content, which contradicts the spec's explicit requirement that the help panel is NOT context-sensitive.
Likelihood: 100% reproducible — the context-sensitivity is hardcoded.
Priority: Medium

Location

File: src/cleveragents/tui/widgets/help_panel_overlay.py — resolve_help_context(), render_help_panel(), _CONTEXT_ITEMS
File: src/cleveragents/tui/app.py — action_help() method

Description

The spec (§10.2 Help Panel) explicitly states:

Context-Sensitivity: The help panel is not context-sensitive. It will always display the same set of global shortcuts regardless of the currently focused panel.

However, the implementation is fully context-sensitive:

resolve_help_context() inspects the current prompt text to determine a context name ("Main Screen", "Slash Commands", "Reference Picker", "Shell Mode")
render_help_panel(context_name) renders different content per context
action_help() in app.py calls resolve_help_context(prompt.value) and passes the result to help_panel.toggle(context_name)

Evidence

resolve_help_context() in help_panel_overlay.py (lines 62–72):

def resolve_help_context(prompt_text: str) -> str:
    stripped = prompt_text.lstrip()
    if stripped.startswith("/"):
        return "Slash Commands"
    if stripped.startswith(("!", "$")):
        return "Shell Mode"
    if "@" in prompt_text:
        return "Reference Picker"
    return "Main Screen"

action_help() in app.py (lines 130–134):

def action_help(self) -> None:
    prompt = self.query_one("#prompt", PromptInput)
    help_panel = self.query_one("#help-panel", HelpPanelOverlay)
    context_name = resolve_help_context(prompt.value)
    help_panel.toggle(context_name)

Steps to Reproduce

from cleveragents.tui.widgets.help_panel_overlay import render_help_panel
main = render_help_panel("Main Screen")
slash = render_help_panel("Slash Commands")
assert main != slash  # True — different content per context

Expected Behavior (from spec §10.2)

Pressing F1 should always display the same help panel content regardless of the current prompt text or focused panel. The resolve_help_context() function should not be called from action_help(), and the help panel should always render the full global shortcut list.

Actual Behavior

Pressing F1 with an empty prompt shows "Main Screen" context help
Pressing F1 while typing a / command shows "Slash Commands" context help
Pressing F1 while typing @ shows "Reference Picker" context help
Pressing F1 while in shell mode shows "Shell Mode" context help

Each context shows different shortcuts, and the spec-required global shortcuts (Navigation, Actions, TUI-Specific categories) are absent from all contexts.

#1356 (UAT: Help panel title is wrong and missing required shortcut categories)
#1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings)

References

Spec §10.2 Help Panel (F1) — "Context-Sensitivity" subsection
src/cleveragents/tui/widgets/help_panel_overlay.py lines 62–72 (resolve_help_context)
src/cleveragents/tui/app.py lines 130–134 (action_help)

## Bug Report: [tui/help-panel] — Help panel is context-sensitive, violating spec requirement ### Severity Assessment - **Impact**: Medium. Users pressing F1 in different input modes (slash command, reference picker, shell mode) will see different help content, which contradicts the spec's explicit requirement that the help panel is NOT context-sensitive. - **Likelihood**: 100% reproducible — the context-sensitivity is hardcoded. - **Priority**: Medium ### Location - **File**: `src/cleveragents/tui/widgets/help_panel_overlay.py` — `resolve_help_context()`, `render_help_panel()`, `_CONTEXT_ITEMS` - **File**: `src/cleveragents/tui/app.py` — `action_help()` method ### Description The spec (§10.2 Help Panel) explicitly states: > **Context-Sensitivity**: The help panel is **not** context-sensitive. It will always display the same set of global shortcuts regardless of the currently focused panel. However, the implementation is fully context-sensitive: 1. `resolve_help_context()` inspects the current prompt text to determine a context name (`"Main Screen"`, `"Slash Commands"`, `"Reference Picker"`, `"Shell Mode"`) 2. `render_help_panel(context_name)` renders different content per context 3. `action_help()` in `app.py` calls `resolve_help_context(prompt.value)` and passes the result to `help_panel.toggle(context_name)` ### Evidence **`resolve_help_context()` in `help_panel_overlay.py` (lines 62–72)**: ```python def resolve_help_context(prompt_text: str) -> str: stripped = prompt_text.lstrip() if stripped.startswith("/"): return "Slash Commands" if stripped.startswith(("!", "$")): return "Shell Mode" if "@" in prompt_text: return "Reference Picker" return "Main Screen" ``` **`action_help()` in `app.py` (lines 130–134)**: ```python def action_help(self) -> None: prompt = self.query_one("#prompt", PromptInput) help_panel = self.query_one("#help-panel", HelpPanelOverlay) context_name = resolve_help_context(prompt.value) help_panel.toggle(context_name) ``` ### Steps to Reproduce ```python from cleveragents.tui.widgets.help_panel_overlay import render_help_panel main = render_help_panel("Main Screen") slash = render_help_panel("Slash Commands") assert main != slash # True — different content per context ``` ### Expected Behavior (from spec §10.2) Pressing F1 should always display the same help panel content regardless of the current prompt text or focused panel. The `resolve_help_context()` function should not be called from `action_help()`, and the help panel should always render the full global shortcut list. ### Actual Behavior - Pressing F1 with an empty prompt shows "Main Screen" context help - Pressing F1 while typing a `/` command shows "Slash Commands" context help - Pressing F1 while typing `@` shows "Reference Picker" context help - Pressing F1 while in shell mode shows "Shell Mode" context help Each context shows different shortcuts, and the spec-required global shortcuts (Navigation, Actions, TUI-Specific categories) are absent from all contexts. ### Related Issues - #1356 (UAT: Help panel title is wrong and missing required shortcut categories) - #1290 (UAT: TUI help panel key bindings are inconsistent with actual app bindings) ### References - Spec §10.2 Help Panel (F1) — "Context-Sensitivity" subsection - `src/cleveragents/tui/widgets/help_panel_overlay.py` lines 62–72 (`resolve_help_context`) - `src/cleveragents/tui/app.py` lines 130–134 (`action_help`)

freemo added the

labels

2026-04-02 18:17:26 +00:00

freemo referenced this issue

2026-04-02 18:19:39 +00:00

[Automated] Product Build Session State #1314

freemo self-assigned this

2026-04-02 18:45:19 +00:00