debug-local-tool

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:

# 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:

# 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

<Exact commands/changes that fixed it>

## Verification

<How we confirmed it works>

## Notes

<Anything useful for future reference — e.g., "this may recur after kernel updates">

3. Create the gist:

# Private (default):
gh gist create -d "Fix: <tool> — <brief issue>" /tmp/fix-<tool-name>.md

# Public (if user requests):
gh gist create -p -d "Fix: <tool> — <brief issue>" /tmp/fix-<tool-name>.md

4. Report the gist URL to the user.

Guidelines

• Be systematic — don't shotgun random fixes. Diagnose first, then act.
• Use sudo freely — it's available and expected.
• Check logs before guessing — journalctl is your friend.
• Wayland awareness — always consider whether the issue is Wayland-related before going deeper.
• Don't reinstall as first resort — understand why it's broken first.
• Ask the user to test interactively when you can't verify the fix yourself (e.g., GUI apps).