Most bugs come back because the fix never matched the cause. You see an error, you form a theory, you patch
the first thing that looks wrong, the symptom disappears for a day, and then it returns — because you
treated a symptom, not a root cause. You are leaving real engineering time on the table every time you skip
straight to the fix.

The Free Debug Engineer Pack enforces a discipline that good engineers apply by hand and most teams skip under
pressure: never fix a bug before you've investigated the root cause, and never trust a diagnosis until
a devil's advocate has challenged it.

It does this with a two-agent protocol. debug-investigator enumerates every plausible cause,
assigns a verification command to each, runs only read-only checks, and reports confirmed versus ruled-out
causes with evidence — it deliberately does not implement the fix. Then hostile-reviewer
takes that diagnosis and argues against it: challenging assumptions, exposing what wasn't checked, and asking
what would have to be true for the fix to fail. Only after the diagnosis survives that challenge do you write code.

This pack is for any developer who ships bugs that come back, burns hours on "obvious" fixes that don't stick,
or wants to stop guessing and start diagnosing. It is a free sample from the full Claude Code Power Pack
at promptbuildship.dev — genuinely useful on its own, and a preview
of the complete toolkit.

Agents

Skills

Prerequisites

• The Claude Code CLI, installed and authenticated. If you do not have it yet, get it at https://claude.ai/code.
• A ~/.claude/ directory (Claude Code creates this on first run).

Step 1 — Unzip the pack

unzip Free-Debug-Engineer-Pack.zip
cd Free-Debug-Engineer-Pack

Step 2 — Copy the agents

Agents are single .md files. Copy them into your user agents directory:

cp agents/*.md ~/.claude/agents/

Step 3 — Copy the skills

Each skill is a directory (it carries its own SKILL.md plus any reference files, scripts, and templates). Copy the directories, not just the files:

cp -r skills/* ~/.claude/skills/

Step 4 — Verify

Restart Claude Code so it reloads agents and skills. Then type @debug in a session. The debug-investigator agent should appear in the suggestions. If it does, the pack is installed.

This is the core of the pack. Follow all three steps in order. Skipping Step 1 or Step 2 is exactly the habit
that lets bugs come back.

1. // Step 1

   Investigate first, fix never

   Invoke debug-investigator with the full symptom description: the exact error message or stack trace, when it happens, and what changed recently (a deploy, a dependency bump, a config edit, an OS update).

   The agent does not jump to a theory. It first enumerates every plausible root cause across all categories — environmental, configuration, code, dependency, state, timing, permissions, and network. For each cause it assigns an exact verification command using only read-only tools (cat, ls -la, stat, grep, systemctl status, journalctl -u, ss -tlnp, id, lsof, ps aux, and similar). It runs the checks — independent ones in parallel — and records the exact command, the exact output, and a verdict of Confirmed, Ruled out, or Inconclusive for each.

   You get back a structured Root Cause Analysis: confirmed cause(s) with the evidence that proves them, ruled-out causes with the evidence that eliminated them, an explicit list of what could not be checked, a confidence level, and a single one-sentence fix recommendation.

   It does not implement the fix. That is intentional. A diagnosis you can inspect is worth more than a patch you have to trust.

   Example "Use the debug-investigator agent. Symptom: the api systemd service exits 30 seconds after start with bind: address already in use on port 8080. Started after this morning's deploy. Nothing else on the box was changed that I know of."

2. // Step 2

   Challenge the diagnosis

   Invoke hostile-reviewer with the debug-investigator findings (and the proposed fix, if you have one drafted).

   This agent plays devil's advocate on behalf of correctness. It asks whether the cited evidence actually proves causation or is just a correlated side effect; which categories of cause were never checked at all; whether a simpler or more common explanation fits the same evidence; whether the proposed fix addresses the confirmed cause or merely masks the symptom; and what could regress that wasn't tested.

   You get back a numbered Challenge Report. Every objection comes with a concrete resolution — the exact command or check that would confirm or refute it — plus a list of surviving concerns if you proceed without addressing them, any items it clears as adequately handled, and a verdict: Proceed, Proceed with caution, or Do not proceed until X is verified.

   If the investigation was thorough, it says so. No blanket vetoes — every objection is actionable.

   Example "Use the hostile-reviewer agent on the debug-investigator diagnosis above. The proposed fix is to add After=network-online.target to the unit file. Challenge whether that actually addresses the confirmed cause."

3. // Step 3

   Verify after the fix

   Once the diagnosis has survived the challenge and you (or a coding agent) have implemented the fix:

   • Run /webapp-testing to drive the running app with Playwright and confirm the user-facing behavior is actually fixed — not just the log line.
   • Run /security-review to catch any security regression the change introduced, especially if the fix touched auth, input handling, data access, or external calls.

   A fix is not done when the error stops printing. It is done when a test proves the behavior is correct and a review proves you didn't open a hole.

debug-investigator

A systematic root-cause investigator that diagnoses bugs, errors, service failures, and regressions without changing anything. It works in three phases: enumerate every plausible cause across all categories, verify each with an exact read-only command (running independent checks in parallel), then produce a structured Root Cause Analysis with confirmed causes, ruled-out causes, inconclusive items, a confidence level, and one fix recommendation per confirmed cause. Its hard rules: no writes of any kind, no stopping at the first plausible cause, evidence over intuition (a cause is confirmed only when command output proves it), and explicit honesty about what it could not check. It is meant to be invoked proactively, before any fix is attempted.

Example scenario A nightly cron job that worked last week now silently produces an empty output file. You invoke debug-investigator with the symptom and the fact that the only recent change was a Python dependency upgrade. It enumerates causes (dependency API change, file permissions on the output path, env differing under cron, disk pressure, stale lock file, and more), verifies each, and reports that the new library version changed a default argument — confirmed by diffing the installed package metadata — while ruling out permissions and disk with evidence.

hostile-reviewer

A hostile-but-honest reviewer whose job is to find the holes in a proposed diagnosis or fix before any code is committed. It reads the diagnosis and fix in full, then challenges across six axes: causation vs. correlation, coverage, alternative explanations, fix-cause alignment, regression risk, and missing verification (both pre- and post-conditions). It produces a numbered Challenge Report where every objection carries the exact check that would resolve it, plus surviving concerns, cleared items, and a clear verdict. It writes no code and issues no blanket vetoes — if the diagnosis is sound, it says so. It is also worth invoking on any significant architectural decision, or whenever a fix has been attempted more than once without success (re-challenge the root-cause assumption).

Example scenario debug-investigator concludes a 500 error is caused by a null user record and recommends a null check. You invoke hostile-reviewer, which objects that "user is null" is a symptom — the real question is why the record is null — points out the session and cache layers were never checked, and returns a verdict of "Proceed with caution: verify the session store is not evicting records under load before shipping the null guard."

/webapp-testing

A toolkit for interacting with and testing local web applications using Playwright. You write native Python Playwright scripts; a bundled scripts/with_server.py helper manages server lifecycle (including multiple servers, such as a backend plus a frontend). The skill follows a decision tree — static HTML gets selectors read straight from the file, dynamic apps use reconnaissance-then-action: navigate, wait for networkidle, screenshot or inspect the DOM, identify selectors from the rendered state, then act. Treat the bundled scripts as black boxes — run them with --help, don't read their source unless a customized solution is genuinely required, so you don't pollute the context window.

Usage example After fixing a form-validation bug, run /webapp-testing to launch the dev server via with_server.py, navigate to the form, submit invalid input, and assert the new error message renders — confirming the fix from the user's point of view, not just in the logs.

python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py

/security-review

An OWASP Top 10 security audit. By default it scopes to the git diff (git diff HEAD or git diff main...HEAD) plus directly-called auth/input/data-access code; you can also point it at specific files or a directory. It works through all ten OWASP categories — broken access control, cryptographic failures, injection, insecure design, security misconfiguration, vulnerable components, authentication failures, integrity failures, logging failures, and SSRF — plus targeted greps for hardcoded secrets, path traversal, unsafe deserialization, and shell injection. It produces a findings report with severity (Critical/High/Medium/Low/Info), file:line, attack vector, and remediation. On request it will apply fixes for unambiguous Critical and High findings and re-run the checks to confirm resolution.

Usage example After a debugging fix that changed how a route loads a file by user-supplied name, run /security-review on the diff. It flags the path-traversal risk where the input flows into open() unsanitized, rates it Critical, and proposes the remediation before you ship.

These chains compose the agents and skills into complete workflows. Run them in order.

1. Standard debug loop

debug-investigator  →  hostile-reviewer  →  fix  →  /webapp-testing

The default loop for any user-visible bug. Diagnose with evidence, have the diagnosis challenged, implement the fix once it survives, then prove the behavior is actually correct in the running app.

2. Security bug investigation

debug-investigator  →  /security-review  →  hostile-reviewer  →  fix

When the bug touches auth, input handling, or data access. Diagnose the root cause, run the security audit so the security findings are on the table before the challenge, let hostile-reviewer weigh the diagnosis against those findings, then fix with both in view — so you don't patch the bug and ship a vulnerability.

3. Regression investigation

debug-investigator (with git diff context)  →  hostile-reviewer  →  /webapp-testing

When something that used to work stopped. Feed debug-investigator the relevant git diff or commit range so it can correlate the regression with what actually changed, have the diagnosis challenged (especially the "this commit caused it" assumption), then confirm the restored behavior end-to-end with Playwright.