debug-helper_skill

Overview

This skill provides systematic debugging strategies, troubleshooting methodologies, and concrete problem‑solving techniques for code, dotfiles, shells, and system issues. It guides you from problem definition through hypothesis testing to verification and documentation, with practical commands and tooling tips for Python, shell, and service-level faults. Use it when you hit bugs, errors, unexpected behavior, or configuration drift and need a repeatable way to diagnose and fix the issue.

How this skill works

I inspect the failure by asking targeted questions about expected vs actual behavior, reproducibility, and recent changes. Then I gather evidence from logs, error traces, git diffs, and environment checks to form ranked hypotheses. You test one hypothesis at a time using logging, debuggers, binary search, or system tracing until the root cause is isolated. Finally, verify fixes, add tests or config guards, and document the root cause to prevent regression.

When to use it

• When a dotfile change breaks shell, tmux, or editor behavior after a sync or install
• When a Python script raises unclear exceptions or behaves differently across machines
• When a service fails to start or a port is unresponsive on your system
• When intermittent failures or race conditions make troubleshooting hard
• When you need a structured plan to reproduce and isolate elusive bugs

Best practices

• Reproduce the issue reliably before changing multiple variables
• Collect logs and stack traces first, then form hypotheses ranked by likelihood
• Test one variable at a time (binary search / comment-halving) to isolate code paths
• Use breakpoints and strategic logging, then remove debug artifacts after fixes
• Record root cause, steps to reproduce, and add tests or config checks to prevent regressions

Example use cases

• Fixing a zshrc change that breaks plugin loading: reproduce, compare previous dotfiles, enable verbose shell tracing (set -x) and bisect changes
• Diagnosing tmux misbehavior after a new tmux.conf: check tmux server processes, reload config, and isolate conflicting key bindings
• Resolving a Python service crash: capture stack trace, run under pdb or cProfile, and verify dependency versions between environments
• Investigating a failing systemd service: inspect journalctl, check unit status, and trace open files with lsof/strace
• Tracking down an intermittent network failure: use ping, curl -v, dns lookups, and reproduce with increased logging or tcpdump