Systematic debugging with pattern learning. Applies hypothesis-driven investigation, evidence collection, and reflection to update pattern confidence.
From apexnpx claudepluginhub benredmond/apex --plugin apexThis skill uses the workspace's default tool permissions.
Integrates with failure-predictor and git-historian agents to provide historical context. Produces evidence that feeds into the reflection step for continuous learning.
Can operate phase-agnostic: debug sessions can happen at any point in the workflow. </overview>
<phase-gate requires="none" sets="none"> <reads-file>./apex/tasks/[ID].md (if task-linked)</reads-file> <appends-section>debug</appends-section> <note>Debug is phase-agnostic - can be invoked at any workflow stage</note> </phase-gate> <principles> - **Evidence-Based**: Every hypothesis needs concrete evidence (error messages, stack traces, git bisect results) - **Pattern-Informed**: Check known patterns or past incidents for failure modes before investigating - **Learn From History**: Check similar past bugs and their resolutions - **Reflective**: Record debugging outcomes to improve future debugging - **Systematic**: Follow structured methodology - no shotgun debugging - **Hypothesis Discipline**: Maximum 3 concurrent hypotheses to prevent scattered investigation </principles> <initial-response> <if-no-arguments> I'll help debug systematically. Please provide either: - A task identifier from `./apex/tasks/` - An error description to investigateUsage: /apex:debug [task-id] or /apex:debug "error message or description"
</if-no-arguments>
<if-arguments>Initialize debug session with provided context.</if-arguments>
</initial-response>
Predict likely failure modes based on historical patterns. Return: Predicted failures with prevention strategies. </agent> </spawn-agents>
</step> <step id="2" title="Reproduce and gather evidence"> <critical> Do NOT proceed without reproducing the bug. Reproducibility is mandatory. </critical> <instructions> 1. **Create minimal reproduction**: - Write smallest test case that triggers the bug - Document exact reproduction steps - If cannot reproduce, investigate intermittency patternsCapture evidence:
Record evidence in the task log:
</instructions>Find: Recent changes, regressions, related fixes. Return: Git intelligence with blame and commit analysis. </agent> </spawn-agents>
<hypothesis-formation> Form hypotheses based on evidence gathered:### Hypothesis 1: [Title]
- **Based on**: [Evidence that supports this]
- **Predicts**: [What we'd see if true]
- **Test**: [How to verify]
### Hypothesis 2: [Title]
...
### Hypothesis 3: [Title]
...
LIMIT: Maximum 3 concurrent hypotheses. If all 3 fail, revisit evidence before forming new ones. </hypothesis-formation>
<root-cause-techniques> **5 Whys Method**: ``` Problem: [Symptom] Why? → [First-level cause] Why? → [Second-level cause] Why? → [Third-level cause] Why? → [Fourth-level cause] Why? → ROOT CAUSE: [Fundamental issue] ```Binary Search (git bisect):
git bisect start
git bisect bad HEAD
git bisect good [known-good-commit]
# Test each midpoint until culprit found
</root-cause-techniques>
</step>
<step id="4" title="Hypothesis testing">
<critical>
Test ONE hypothesis at a time. Make SMALLEST possible change to test.
</critical>
<instructions>
1. **Select hypothesis**: Choose most likely based on evidence
2. **Design minimal test**: Smallest change to verify
3. **Execute test**: Run and observe
4. **Record result**: Document outcome for each hypothesis
5. **Iterate or escalate**:
- If confirmed → proceed to fix
- If refuted → test next hypothesis
- If 3+ hypotheses fail → question assumptions, escalate
</instructions>
<testing-discipline>
For each hypothesis:
```markdown
### Testing Hypothesis [N]: [Title]
- **Test method**: [What we're doing]
- **Expected if true**: [Prediction]
- **Actual result**: [What happened]
- **Conclusion**: CONFIRMED | REFUTED | INCONCLUSIVE
```
</testing-discipline>
<escalation-trigger>
If 3 hypotheses fail:
1. Re-examine evidence - something was missed
2. Question architectural assumptions
3. Ask user for additional context
4. Consider spawning systems-researcher for deeper analysis
</escalation-trigger>
</step>
<step id="5" title="Fix implementation">
<critical>
Create failing test BEFORE implementing fix. TDD for bug fixes.
</critical>
<instructions>
1. **Write failing test**: Test that reproduces the exact bug
2. **Verify test fails**: Confirm it catches the bug
3. **Implement minimal fix**: Single change addressing root cause
4. **Verify test passes**: Bug is fixed
5. **Run full test suite**: No regressions introduced
</instructions>
<fix-checklist>
- [ ] Failing test written that reproduces bug
- [ ] Test verified to fail before fix
- [ ] Fix implemented (single, minimal change)
- [ ] Bug-specific test now passes
- [ ] Full test suite passes
- [ ] No new lint errors
</fix-checklist>
<validation-commands>
```bash
# Run targeted test
npm test -- [test-file]
npm test
npm run lint
</validation-commands>
</step>
<step id="6" title="Reflection and learning">
<critical>
Without reflection, debugging learnings are lost. This step is MANDATORY.
</critical>
<instructions>
1. **Document root cause**: Clear explanation of what caused the bug
2. **Document fix**: What changed and why
3. **Identify patterns**:
- Did existing patterns help? (update confidence)
- Discovered new failure mode? (propose new pattern)
4. **Submit reflection**: Record a structured reflection with evidence
5. **Update task**: Complete debug section
</instructions>
<reflection-template>
```markdown
### Debug Summary
- **Root Cause**: [What actually caused the bug]
- **Fix**: [What we changed]
- **Prevention**: [How to prevent similar bugs]
### Patterns
- **Used**: [Patterns that helped, with outcomes]
- **Discovered**: [New failure modes or fixes]
### Learnings
- [Key insight 1]
- [Key insight 2]
</reflection-template>
</step>
</workflow>
<output-format>
Append to task file `./apex/tasks/[ID].md`:
<debug>
<metadata>
<timestamp>[ISO]</timestamp>
<duration>[Time spent]</duration>
<hypotheses-tested>[N]</hypotheses-tested>
</metadata>
<reproduction>
<reproducible>true|false</reproducible>
<steps>[Reproduction steps]</steps>
<minimal-case>[Test case location if created]</minimal-case>
</reproduction>
<investigation>
<evidence>
<error-message>[Exact error]</error-message>
<stack-trace>[Relevant portions]</stack-trace>
<related-commits>[Git history findings]</related-commits>
<pattern-matches>[Patterns that matched]</pattern-matches>
</evidence>
<hypotheses>
<hypothesis id="1" status="confirmed|refuted|untested">
<title>[Hypothesis]</title>
<evidence>[Supporting evidence]</evidence>
<test-result>[What happened when tested]</test-result>
</hypothesis>
</hypotheses>
</investigation>
<root-cause>
<description>[What actually caused the bug]</description>
<five-whys>[If used, the chain of whys]</five-whys>
</root-cause>
<fix>
<description>[What was changed]</description>
<files-modified>[List of files]</files-modified>
<test-added>[New test location]</test-added>
</fix>
<reflection>
<patterns-used>
<pattern id="[PAT:ID]" outcome="worked|tweaked|failed">[How it helped]</pattern>
</patterns-used>
<learnings>
<learning>[Key insight]</learning>
</learnings>
<prevention>[How to prevent similar bugs]</prevention>
</reflection>
</debug>
</output-format>
<antipatterns>
<avoid name="Shotgun Debugging">
Making random changes hoping something works.
**Instead**: Form hypotheses based on evidence, test systematically.
</avoid>
<avoid name="Symptom Fixing">
Quick patches that don't address root cause.
**Instead**: Use 5 Whys to find fundamental issue.
</avoid>
<avoid name="Evidence-Free Hypotheses">
Guessing without data.
**Instead**: Every hypothesis must cite specific evidence.
</avoid>
<avoid name="Hypothesis Sprawl">
Forming 10+ hypotheses without testing any.
**Instead**: Limit to 3 concurrent, test each fully.
</avoid>
<avoid name="Skipping Reflection">
Fixing bug but not recording learnings.
**Instead**: Always record a reflection at the end.
</avoid>
</antipatterns>
<success-criteria>
- Bug reproduced (or intermittency documented)
- Evidence gathered and recorded in the task log
- Root cause identified through systematic investigation
- Fix implemented with failing test first
- All tests pass including new regression test
- Reflection recorded with debugging outcomes
- Task file updated with `<debug>` section
- Checkpoints recorded at each major step
</success-criteria>
<next-steps>
After debugging:
- If part of existing task: Continue with current workflow phase
- If standalone debug: `/apex:ship [identifier]` to finalize and reflect
</next-steps>
</skill>