TUI Troubleshooting: Freezes, Hangs, Blank Screens, and Terminal State Corruption

Use this skill when the user reports that a TUI "froze", "hung", "blanked the terminal", "stopped accepting input", "left the terminal broken", or "works in one terminal but not another". Treat these reports as terminal lifecycle failures until proven otherwise.

First response rule

Do not give a shallow checklist. Establish the failure class, inspect startup and cleanup order, and look for a concrete lifecycle bug:

1. Does the app enter raw mode, alternate screen, mouse, focus, or bracketed paste?
2. Is every mode restored on normal exit, Ctrl-C, exception, panic, rejected promise, and early return?
3. Is stdin flowing after terminal setup?
4. Does the app render and flush at least one frame before waiting on async work or input?
5. Can logs, stderr, background tasks, or child processes write into the same terminal surface?
6. Does the bug reproduce only in tmux, SSH, Windows/ConPTY, CI, or a non-TTY pipe?

High-probability freeze causes

Prioritize these before exotic terminal protocol issues: