Skip to content

TUI_REFACTOR.md

Latest commit

 

History

History
70 lines (52 loc) · 3.23 KB

TUI_REFACTOR.md

File metadata and controls

70 lines (52 loc) · 3.23 KB
Raw

TUI Refactor Plan — shotgun-cli

Generated by the tui-refactor skill. No source files were modified — this is an actionable redesign + migration plan. To implement, execute the milestones below; to verify afterwards, run tui-validator and diff against the captured baseline.

Summary (10-second read)

  • TUI: shotgun-cli · Framework: Bubble Tea v1.3.5 + lipgloss + bubbles (Go)
  • Ambition chosen: conservative cleanup (IA preserved; both wizard + config TUI in scope)
  • State of the app: already mature — centralized Nord theme, non-blocking async coordinators, context-grouped help, per-step validation. Gaps are refinement-level.
  • Findings: 0 blocker · 5 major · 5 minor · 0 cosmetic
  • Plan: 4 milestones, 10 items, mostly additive. F-keys retained; 2 approved behavior changes (Esc, template Enter).
Top issue Severity Fix
Dot band ..... across the bottom of every screen major M1 · P010
Footer key hints truncate on narrow terminals major M2 · P006
Function-key-only nav (F5/F7/F8/F9) major M3 · P007 (add Tab/letter aliases)
Tree focus highlight obscures the label major M1 · P004
Esc repurposed as focus toggle in inputs major M3 · P008

Phase-4 decisions (from the user)

  • Conservative cleanup — keep the linear wizard + separate config TUI.
  • F-keys stay; add Tab/Shift+Tab/r/s/g aliases (additive).
  • Esc = cancel/leave, Tab = textarea focus toggle.
  • Whole-app scope; align shared chrome across both programs.

Gap analysis

5 major + 5 minor findings — full detail in the workspace: ~/.cache/tui-refactor/shotgun-cli/20260520T165320Z/02-gap-analysis.md (structured: …/findings.json).

Target design

…/03-target-design/ — overview, the File-Selection before→after wireframe, and the target keybinding map with change log.

Refactor plan (milestones)

  1. M1 — Design-system foundation (low risk, invisible): P004 color tiers + readable selection; P010 remove dot band.
  2. M2 — Shared chrome: P005 anchor header/body/status-bar layout; P006 responsive shared status bar; P003 min-size guard.
  3. M3 — Keybinding ergonomics: P007 F-key aliases; P008 Esc=cancel / Tab=focus / unified selection; P009 unified quit semantics.
  4. M4 — Per-screen polish: P011 roll the new primitives across all screens, File Selection → Review → Template → Task → Rules → Config.

Full file-level detail (what/where/how/preserves/effort/validation per item): …/04-refactor-plan.md.

Before gallery (captured live via tui-validator on Wayland)

  • ~/.cache/tui-refactor/shotgun-cli/20260520T165320Z/before/01-file-selection.png
  • ~/.cache/tui-refactor/shotgun-cli/20260520T165320Z/before/help-overlay.png
  • ~/.cache/tui-refactor/shotgun-cli/20260520T165320Z/before/02-template-selection.png
  • ~/.cache/tui-refactor/shotgun-cli/20260520T165320Z/before/wide-160x40.png

Next step

Implement M1→M4 (each as a small, buildable PR). Then run tui-validator on the result and diff against the before/ gallery to prove the fixes landed with no regression.

🤖 Generated with Claude Code — tui-refactor skill