debug-local-tool

Files (1)

• SKILL.md

SKILL.md (first lines)

# Debug Local Tool / Application

Interactive debugging skill for when a local tool, application, or service on the user's workstation isn't behaving correctly.

## System Context

- **OS**: Ubuntu (currently 25.04+, check `lsb_release -a` if needed)
- **Desktop**: KDE Plasma on Wayland
- **Display**: Wayland (NOT X11 — this matters for screen capture, clipboard, GPU, and app compatibility)
- **GPU**: AMD Radeon RX 7700 XT / 7800 XT (Navi 32, gfx1101) — ROCm available
- **Audio**: PipeWire
- **CPU**: Intel Core i7-12700F
- **RAM**: 64 GB
- **Sudo**: Available — use freely for diagnostic and fix commands

## Debugging Approach

Work **interactively** with the user. Don't dump a wall of "try this, try that" — investigate systematically:

### 1. Identify what's broken

Ask the user (if not already clear):
- What tool/app?
- What happens when they try to use it? (error message, silent failure, crash, hang?)
- Did it work before? What changed?

### 2. Gather diagnostic info

Run these as appropriate — don't run all of them blindly, pick what's relevant:

```bash
# Is it installed?
which <tool> || dpkg -l | grep <tool> || flatpak list | grep -i <tool> || snap list | grep <tool>

# What version?
<tool> --version

# Is a service involved?
systemctl status <service>
journalctl -u <service> --no-pager -n 50

# Process running / stuck?
pgrep -a <tool>

# Recent logs
journalctl --user -n 100 --no-pager | grep -i <tool>

# Desktop app crash?
coredumpctl list | tail -10

# Permissions?
ls -la $(which <tool>)

# Dependencies?
ldd $(which <tool>) | grep "not found"

# Package integrity
dpkg -V <package> 2>/dev/null

# Flatpak/Snap specific
flatpak info <app-id>
snap info <snap-name>
```

### 3. Wayland-specific checks

Many issues on this system are Wayland-related. Check:
- Does the app need `--ozone-platform=wayland` or similar flags? (Electron apps)
- Is the app trying to use X11 APIs? Check for `xdg`, `xdotool`, `xclip` dependencies that need Wayland equivalents (`wl-copy`, `wl-paste`, `ydotool`)
- Screen capture / recording tools may need PipeWire portal access
- Check `XDG_SESSION_TYPE` is `wayland`
- Electron/Chromium apps: may need `--enable-features=UseOzonePlatform --ozone-platform=wayland`

### 4. Common failure patterns

| Symptom | Likely cause |
|---------|-------------|
| App launches but blank/black window | Wayland compatibility, try with `QT_QPA_PLATFORM=xcb` or Electron flags |
| Clipboard not working | Using xclip instead of wl-copy/wl-paste |
| Screen recording fails | Missing PipeWire portal, xdg-desktop-portal-kde not running |
| GPU/ROCm tool fails | Wrong gfx target, check `HSA_OVERRIDE_GFX_VERSION` |
| Audio tool fails | PipeWire issue, check `wpctl status`, `pw-cli ls` |
| Segfault on launch | Missing lib, check `ldd`, check coredump |
| "Permission denied" | Flatpak sandbox, snap confinement, or missing group membership |
| Python tool broken | Wrong Python version or venv, check `which python3`, pip path |
| Node tool broken | Wrong Node version, check `node -v`, nvm status |

### 5. Fix it

- Apply the fix directly — don't just suggest it.
- If the fix requires a config change, make the change.
- If a package needs reinstalling, do it.
- If a service needs restarting, restart it.
- **Verify the fix** — run the tool again or ask the user to confirm.

### 6. Document the fix

After a successful fix, create a GitHub gist documenting what happened:

1. Ask the user: **"Public or private gist?"** (default to private if they don't care)
2. Write a markdown file to `/tmp/fix-<tool-name>.md` with this structure:

```markdown
# Fix: <Tool Name> — <Brief Description of Issue>

**Date:** YYYY-MM-DD
**System:** Ubuntu <version>, KDE Plasma, Wayland
**Tool:** <tool name and version>

## Problem

<What wasn't working, including error messages>

## Root Cause

<Why it was broken>

## Fix

From danielrosehill/Linux-Packaging-Plugin, MIT.

More from danielrosehill/Linux-Packaging-Plugin