debug-linux-desktop

Debug Linux Desktop

Symptom-first diagnostic playbook for Linux desktop systems. The user is in pain — be systematic, prove each hypothesis with a command, and don't guess.

Operating Principles

1. Prove before fixing. Every hypothesis needs a confirming diagnostic command before you suggest a fix. Linux desktop issues are heavily multi-causal — a black screen could be GPU driver, display server, display manager, kernel module, or kmsfb fighting fbcon. Running dmesg | tail -50 and journalctl -b -p err is almost always step one.

2. Identify the environment first. Fixes are distro-, init-, session-, and driver-specific. Before recommending anything, capture the baseline:

   . /etc/os-release && echo "$PRETTY_NAME" && uname -r
   echo "Session: ${XDG_SESSION_TYPE:-unset} / Desktop: ${XDG_CURRENT_DESKTOP:-unset}"
   loginctl show-session "$(loginctl | awk '/seat/{print $1; exit}')" -p Type -p Remote 2>/dev/null
   lspci -k | grep -EA3 'VGA|3D|Display'
   

3. Don't reset the system without explicit user approval. Reinstalling drivers, regenerating initramfs, or rebooting are user-confirmed actions. The user's CLAUDE.md is explicit on this.

4. Read logs before reading forums. dmesg, journalctl, ~/.local/share/xorg/Xorg.0.log, ~/.cache/gdm/session.log are authoritative. Forum posts may be outdated or distro-mismatched. If you do search the web (via WebSearch/WebFetch), prefer Arch wiki, Fedora docs, freedesktop.org, kernel.org bug tracker, and Phoronix over random Stack Overflow answers.

5. Use sequential thinking on complex multi-symptom issues. Multi-monitor + Nvidia + Wayland + suspend bug is a 4-axis problem. Externalize the reasoning.

Step 0: Capture Context

Before suggesting anything, ask the user (or detect from terminal access) the answers to these. Don't loop more than once — make reasonable assumptions if the user is short on time.