Task: Create VIEWSPEC.md for a Single TUI View

Task: Create VIEW_SPEC.md for a Single TUI View

Objective

Produce a VIEW_SPEC.md that serves as the deep, per-view design specification for one view in a rich, full-screen terminal UI application (lazygit / k9s / spotify-tui style): the view shell (total grid, frame characters, status-bar position, title bar, help-hint footer); per-panel layout (position, dimensions, resize behavior, border treatment, title, content rendering, scrolling, selection model, in-panel states); mode-specific layouts; per-key behavior in each panel including conflict resolution; focus mechanics; status-bar composition; state-specific layouts; terminal-capability degradation across color depth, Unicode, and minimum-size tiers; mouse behavior; and external editor / shell-out invocation. The defining claim — and the definition of "done" — is that an implementing agent reading TUI_IA.md's blueprint for the view + DESIGN.md's terminal style tokens + this VIEW_SPEC.md composes the view exactly as designed across every supported terminal capability and mode, without inventing layout, keybinding, focus, or degradation decisions of its own.

VIEW_SPEC is a Tier 2, opt-in artifact. Most views stay with their lightweight per-view blueprint inline in TUI_IA.md. A view earns a dedicated VIEW_SPEC only when it meets the selection criteria: composition would exceed roughly thirty inline lines; multi-panel layout with non-trivial panel-resize or focus behavior; multiple modes whose layouts diverge materially; keybinding conflicts that need explicit resolution rules; complex terminal-capability degradation across multiple distinct fallback tiers; non-trivial mouse interactions; multiple work units touch the same view; or the view is the application's flagship surface. Views not meeting any of these stay with inline blueprints in TUI_IA.md.

The commonest violation is overlapping concerns with TUI_IA — redefining panels, modes, keybindings, primary action, data dependencies, or traceability. Those belong in TUI_IA. VIEW_SPEC owns composition, mode-specific layouts, focus mechanics, status-bar composition, state-specific layouts, terminal-capability degradation, mouse behavior, and external-program invocation — and nothing else from TUI_IA's surface.

Inputs

1. View identifier (required) — the stable view ID from TUI_IA.md (e.g., StatusView, LogView, DashboardView). This is the primary key for the spec and the value of the view_id frontmatter field.
2. TUI_IA.md (required) — provides the view's lightweight blueprint to extend: layout reference, panel inventory, modes available, keybindings, default focus, primary action, data dependencies, full state matrix, entry/exit points. Read the blueprint entry for the named view end-to-end before drafting; also read the Layout Model, Mode Model, Global Keybinding Matrix, Focus Model, and Terminal Capability Strategy sections — they bound the design space for this VIEW_SPEC.
3. DESIGN.md (required if present) — terminal-style tokens. Cite by stable name: color tokens for each color-depth tier including monochrome fallback; glyph tokens with Unicode-rich and ASCII fallback; frame-character set (single, double, rounded, ASCII fallback); status-bar segment style; motion / animation tokens for terminals (spinner frame counts, cursor blink rules); density tokens. If DESIGN.md is absent, surface the missing-token need in section 12 — do not invent tokens here.
4. Sibling VIEW_SPEC.md files (optional, auto-discovered) — discovery mechanism: walk the entry points and exit points in this view's TUI_IA blueprint and load any sibling VIEW_SPEC at tui-views/<sibling-id>/VIEW_SPEC.md. Used only to align focus-restoration contracts and external-editor re-entry behavior at boundaries.
5. Prior tui-views/<view-id>/VIEW_SPEC.md (optional, auto-discovered — only if refining) — read fully; preserve every resolved open question and every panel-internal naming choice. Re-run citations against the current TUI_IA and DESIGN.md — do not assume a stale token name or a stale panel name from TUI_IA is still valid.

The output file is conventionally placed at tui-views/<view-id>/VIEW_SPEC.md in the consuming project, where <view-id> matches the view_id frontmatter field exactly.

Rules

Completeness rules

• Every section in the Output Format template is mandatory. Conditional sections (mouse, external editor, status bar) declare their inapplicability with the verbatim "not supported" / "not applicable" sentence specified in the template — they are never silently omitted.
• Every panel listed in TUI_IA's blueprint for this view appears in section 3 by the same name, in the same order, with no panels added and no panels dropped.
• Every mode listed in TUI_IA's blueprint for this view appears in section 4 with its own layout description. If the view is single-mode, section 4 reads "Single mode (normal); no mode-specific layouts." verbatim.
• Every state from TUI_IA's state matrix for this view that materially changes layout appears in section 8. States whose layout matches "default / populated" are listed as "{StateName} — Inherits default layout — no panel changes." rather than dropped silently.
• Every capability tier defined in DESIGN.md is documented in section 9. If DESIGN.md defines tiers truecolor, 256-color, 16-color, monochrome, unicode-rich, unicode-basic, ascii-only, every one appears with a per-view rule.
• The Open Questions section (§ 12) must be empty unless genuinely ambiguous. If you cannot resolve a question from TUI_IA + DESIGN.md, surface it rather than inventing.

Precision rules

• Use exact names — TUI_IA panel names verbatim, TUI_IA mode names verbatim, DESIGN.md token names verbatim, TUI_IA keybinding notation verbatim. Do not paraphrase a panel name from TUI_IA into a "more descriptive" variant.
• Cite keybindings using a consistent notation: Ctrl-x for Ctrl modifier, Ctrl-Shift-X for Ctrl-Shift modifier, gG for chord sequences, <Esc> for non-printable special keys, Tab and Shift-Tab written out. Match TUI_IA's notation when it differs.
• State exact values for every measurable: panel widths in columns or percentages, panel heights in rows or percentages, minimum overall terminal size in cols × rows, hard-refusal threshold in cols × rows, minimum and maximum panel dimensions, scrollbar width if any.