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.

Usage: /apex:debug [task-id] or /apex:debug "error message or description"

Initialize debug session with provided context.

Predict likely failure modes based on historical patterns. Return: Predicted failures with prevention strategies.

Capture evidence:

• Error messages (exact text)

• Stack traces (full trace)

• Logs (relevant entries)

• Environment state (versions, config)

• Recent changes (git log)

Record evidence in the task log:

Find: Recent changes, regressions, related fixes. Return: Git intelligence with blame and commit analysis.

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.

Binary Search (git bisect):

git bisect start git bisect bad HEAD git bisect good [known-good-commit]

Test each midpoint until culprit found

Run full suite

npm test

Lint check

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>

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

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