Task: Generate TUIIA.md — Terminal UI Information Architecture Registry

Task: Generate TUI_IA.md — Terminal UI Information Architecture Registry

Objective

Produce a TUI_IA.md that serves as the single source of truth for a rich terminal UI application's information architecture: the layout model (panels, splits, fixed vs flexible regions), the mode model (normal / edit / command / visual / search, vim-style or bespoke — "modeless" is a valid answer), the keybinding matrix, the focus model, the full view-template inventory, per-view blueprint (purpose, layout, modes available, keybindings, default focus, primary action, data dependencies, full state matrix, entry/exit points), multi-view flows, shared surfaces (command palette, dialogs, help overlay, status bar, notifications, search overlay, external-editor invocation), terminal capability strategy (color depth, Unicode vs ASCII fallback, mouse, minimum terminal size, reserved keys, clean exit), and bidirectional traceability from product use cases to views. An agent or developer reading this document knows exactly what views exist, how panels compose into each view, which keys do what in which mode, which panel is focused, how the app degrades on small or monochrome terminals, and how every use case is realized on the TUI surface — without making any independent layout, keybinding, or mode decisions. TUI_IA sits between product requirements (proposal, use cases) and per-unit TUI SPECs, the same way WEB_IA sits between product requirements and per-unit web SPECs.

Inputs

1. Product / proposal document (required) — product purpose, target users, and rationale. Sets the scope and audience frame for the IA.
2. Use cases document (required) — enumerates user interactions and jobs-to-be-done. Primary input. Every use case with a TUI surface must map to one or more views in the inventory.
3. Architecture document (optional but recommended) — TUI framework choice (bubbletea, textual, ratatui, blessed, tview, ncurses, prompt-toolkit, etc.), language, state management, event loop model, auth model. Informs layout conventions, keybinding style, and shared-surface choices. If absent, infer conservative defaults and flag non-obvious choices as open questions.
4. Existing TUI codebase (auto-discovered) — discover current views, panels, keybindings, and layout from source (e.g., bubbletea tea.Model implementations, textual Screen classes, ratatui Widget trees, blessed screen.append calls). Treat as reference only — TUI_IA is the target state, not a mirror of the current state.
5. Decision documents (optional) — architectural decisions that constrain the IA (e.g., "the app is modeless — no vim modes", "status bar always shows branch and sync state", "q quits from any view").
6. Sibling IAs (optional) — if CLI_IA.md, WEB_IA.md, MOBILE_IA.md, or VOICE_IA.md exist, use-case traceability must be consistent across them. A product that ships both a simple CLI (one-shot commands) and a TUI (interactive full-screen) gets both CLI_IA.md and TUI_IA.md; they describe disjoint surfaces and must not claim the same use case as primary on both without explicit justification.
7. Interface contract (optional) — if INTERFACES.md is present, per-view data dependencies may reference endpoints by EP-name; wire formats are owned by INTERFACES.md, not redefined here.

The user may override scope (e.g., "only the main TUI, not the admin-mode TUI"). Support that by recording the narrowed scope in the Identity & Context section and excluding out-of-scope views from the inventory.

Scope note: this skill covers rich terminal UI applications — full-screen interactive terminal programs with multi-view navigation, panel-based layouts, and keybinding-driven interaction (lazygit, k9s, htop/btop, zellij, ranger, bubbletea apps, textual apps). Simple CLI tools that read args and print output belong in CLI_IA.md. Interactive REPLs with prompt-based interaction (no alt-screen, no multi-panel layout) are borderline — if the REPL has a persistent UI, multiple views, and keybindings beyond readline, document it here; otherwise, document it in CLI_IA.md.

Workflow

TUI IA generation proceeds in seven phases: scope, centralized models (layout / mode / focus / globals), inventory, per-view blueprint, flows and shared surfaces, terminal capability and global states, traceability and validation. Phases are sequential — later phases depend on earlier decisions — but revisit earlier phases if a later phase reveals a gap.

Phase 1: Scope & Audience

Derive from the product doc and use cases document the target TUI surface (single-view full-screen app, multi-view navigator, dashboard, editor-style app) and the audiences the IA serves (end user, operator, contributor). Record explicitly what is not in scope for this TUI_IA document — GUI wrappers, web surfaces, simple CLI binaries, embedded terminal widgets in other IDEs. Keep audience treatment thin — named user types and their 3–7 top tasks per audience. No deep persona work.

Phase 2: Layout, Mode, Focus, and Global Keybindings

Decide the centralized models before enumerating views. This is the analogue of Phase 2 in CLI_IA.md (command grammar and globals) and Phase 2 in WEB_IA.md (URL strategy and global navigation): per-view drift is prevented by stating the cross-cutting rules once and enforcing them across every view.

Decide, in order:

Layout Model

• Root layout — single-view / split-screen / tabbed / overlay-based / wizard-linear