dogfood-tui git:20260413.4a9c08aA

Immutable. This exact content never changes and is served at /api/v1/blob/ef4b76de349627d6.

---
name: dogfood-tui
description: Structured TUI dogfooding and QA workflow using agent-tty. Use for exploratory testing, bug hunting, release-readiness validation, and UX review of terminal applications.
advertise: true
---

# Dogfooding TUIs with agent-tty

Use this skill when the user wants structured exploratory testing, bug hunting, release-readiness validation, or UX review for a terminal application or TUI.

## Prerequisites

This workflow assumes the `agent-tty` core skill is already loaded.
If it is not, load it first with `agent-tty skills get agent-tty`.
Use this skill as the specialized QA layer on top of the core terminal automation workflow.

## Dogfooding Workflow

1. **Create an isolated home** so artifacts and session state stay reviewable and do not pollute the real user environment.
2. **Check renderer and browser prerequisites** with `doctor --json` before any screenshot or recording work.
3. **Create the session** with a known shell or launcher command and capture the returned session ID.
4. **Launch the target app intentionally**:
   - Use `run` for fast setup commands or scripted launches.
   - Use `type` for literal keystroke-by-keystroke text entry that should appear in the session.
   - Use `send-keys` for control input such as arrows, Enter, Escape, Ctrl+C, or function-key navigation.
5. **Wait on observable state** with `wait` instead of blind sleeps:
   - `--text` when a label, prompt, or status message should appear.
   - `--screen-stable-ms` when the UI is animating or repainting.
   - `--idle-ms` when command completion matters more than screen text.
6. **Capture the current screen state** with `snapshot --format text --json` for searchable text evidence.
7. **Capture visual proof** with `screenshot --json` whenever layout, color, cursor, or rendering quality matters.
8. **Export motion proof** with `record export --format webm --json` when the issue involves navigation, animation, resize behavior, focus handling, or transient corruption.
9. **Repeat the loop** for every meaningful scenario: startup, first-run prompts, resize, help flows, error handling, and teardown.
10. **Destroy the session** when the investigation is complete.

## Recommended Session Skeleton

```bash
DOGFOOD_HOME="$(mktemp -d)"
agent-tty --home "$DOGFOOD_HOME" doctor --json
SESSION_ID=$(agent-tty --home "$DOGFOOD_HOME" create --json -- /bin/bash | jq -r '.result.sessionId')
agent-tty --home "$DOGFOOD_HOME" run "$SESSION_ID" '<launch-command>' --no-wait --json
agent-tty --home "$DOGFOOD_HOME" wait "$SESSION_ID" --screen-stable-ms 1000 --json
agent-tty --home "$DOGFOOD_HOME" snapshot "$SESSION_ID" --format text --json
agent-tty --home "$DOGFOOD_HOME" screenshot "$SESSION_ID" --json
agent-tty --home "$DOGFOOD_HOME" record export "$SESSION_ID" --format webm --json
agent-tty --home "$DOGFOOD_HOME" destroy "$SESSION_ID" --json
```

## Evidence Checklist

Collect enough evidence that another reviewer can reproduce the result without guessing:

- Exact repro commands, including the launch command and every subsequent `run`, `type`, or `send-keys` action.
- Terminal dimensions used for the repro, especially if layout or wrapping is part of the issue.
- At least one screenshot path for the failing or noteworthy state.
- A WebM export path when motion, navigation sequence, or transient rendering matters.
- Snapshot text for the most relevant terminal states so reviewers can search output quickly.
- Expected behavior versus actual behavior written in plain language.
- Whether the issue reproduces consistently, intermittently, or only after a specific setup sequence.
- Cleanup notes, especially if the app leaves background state, temp files, or a broken terminal mode behind.

## Issue Taxonomy

Use consistent labels and notes so findings can be triaged quickly:

- **Rendering corruption** — garbled characters, color loss, double paint, cursor artifacts, or stale cells.
- **Resize/layout** — wrapping bugs, clipped panes, overlapping widgets, incorrect recompute after resize, or unusable small-screen behavior.
- **Focus/input** — lost keystrokes, wrong focused widget, modal traps, broken shortcuts, or incorrect key interpretation.
- **Scrollback** — missing history, jumpy scrolling, incorrect paging, or broken mouse wheel behavior.
- **Alt-screen** — failure to enter or exit cleanly, leaked UI frames, or shell prompt corruption after exit.
- **Copy/paste** — paste corruption, bracketed-paste issues, selection problems, or unsafe multiline submission behavior.
- **Performance/startup** — slow launch, delayed first paint, high-latency navigation, or visible stutter.
- **Crash/recovery/state loss** — panic, unexpected exit, broken resume path, lost form state, or inconsistent restoration after restart.

## Report Template

Use this structure when handing findings back to the user or a maintainer:

- **Title:** concise issue summary
- **Environment:** OS, shell, app version/commit, terminal dimensions, and whether `doctor --json` passed
- **Reproduction steps:** numbered sequence with the exact `agent-tty` commands and key inputs used
- **Evidence bundle:** paths to snapshot text, screenshot PNG, WebM, and any additional logs
- **Expected behavior:** what should have happened
- **Actual behavior:** what happened instead
- **Impact:** severity, user-facing risk, and whether it blocks release-readiness
- **Workaround:** any known mitigation or safer path
- **Regression suspicion:** whether this looks new, long-standing, or tied to a recent change

Prefer concise, repeatable repros and artifact-backed findings over narrative descriptions. The goal is a reviewable proof bundle, not just an anecdote.