raisedadead/debug

dp-cto:debug — Structured Root-Cause Debugging

<!-- Two-layer deep-reasoning signal: debugger.md frontmatter `effort: high` sets agent-scope depth; this keyword sets skill-scope depth when the skill body is loaded without agent dispatch. Both are intentional. -->

Use ultrathink for diagnosis — symptoms mislead, root causes hide.

Read ${CLAUDE_PLUGIN_ROOT}/shared/cto-boundaries.md

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you have not completed the investigation phase, you are not allowed to propose a fix. No exceptions.

Protocol

1. Gather Error Report

Collect from the user:

• Error message or failing behavior (exact text, stack traces)
• Steps to reproduce
• Affected file paths (resolve concrete paths — never placeholders)

If the user's description is vague, ask clarifying questions before dispatch. One question per message.

2. Dispatch Debugger Agent

Dispatch debugger via the Agent tool with subagent_type: "dp-cto:debugger".

The agent prompt must include:

• The error report (exact error text, reproduction steps)
• Concrete file paths to investigate
• The verification command to reproduce the failure

The debugger agent runs the 4-phase root cause investigation protocol (reproduce, analyze, hypothesize, report). It is read-only — it cannot modify code.

3. Validate Receipt

On agent completion, extract the structured receipt from <!-- RECEIPT:START/END --> markers. Validate:

• root_cause — file:line with explanation (not vague)
• evidence — commands run and their output
• suggested_fix — concrete change description
• confidence — high, medium, or low

If the receipt is missing or incomplete, report the gap. Do not fabricate findings.

4. Present and Decide

Present the debugger's findings to the user with root cause, evidence, and suggested fix. Then offer next steps:

• Fix it — dispatch an implementer agent (via /dp-cto:run) with the suggested fix and file scope
• Investigate further — re-dispatch debugger with refined focus
• Manual — user handles it themselves

Read ${CLAUDE_SKILL_DIR}/references/red-flags.md before proceeding. Read ${CLAUDE_SKILL_DIR}/references/user-signals.md before proceeding. Read ${CLAUDE_SKILL_DIR}/references/anti-rationalization.md before proceeding. Read ${CLAUDE_SKILL_DIR}/references/quick-reference.md before proceeding. Read ${CLAUDE_SKILL_DIR}/references/no-root-cause-protocol.md before proceeding.

NEVER

1. NEVER investigate or debug inline — always dispatch the debugger agent
2. NEVER propose a fix before the debugger completes root cause investigation
3. NEVER auto-invoke a fix — present findings and let the user decide
4. NEVER accept a receipt without file:line evidence
5. NEVER rationalize skipping process — check the anti-rationalization table
6. NEVER stack fixes on top of failed fixes