---

name: apex:debug description: Systematic debugging with APEX pattern learning. Applies hypothesis-driven investigation, evidence collection, and reflection to update pattern trust scores. argument-hint: [task-identifier or error-description]

Integrates with failure-predictor and git-historian agents to provide historical context. Produces evidence that feeds into apex_reflect 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.

// If creating new task apex_task_create({ intent: "Debug: [error summary]", type: "bug", tags: ["debugging", "investigation"] })

Copy</mcp-calls>

<spawn-agents>
<agent type="apex:failure-predictor">
**Error Context**: [Error message or symptom]
**File Context**: [Suspected files if known]

Predict likely failure modes based on historical patterns.
Return: Predicted failures with prevention strategies.
</agent>
</spawn-agents>

<mcp-checkpoint>
```javascript
apex_task_checkpoint(taskId, "DEBUG: Initialized debug session", 0.3)

1. Capture evidence:

   • Error messages (exact text)
   • Stack traces (full trace)
   • Logs (relevant entries)
   • Environment state (versions, config)
   • Recent changes (git log)

2. Record evidence via MCP:

apex_task_append_evidence(taskId, "file", "Reproduction test case at [location]", { file: "[test file]" } )

Copy</mcp-calls>

<reproduction-checklist>
- [ ] Bug reproduces consistently OR intermittency pattern documented
- [ ] Exact error message captured
- [ ] Stack trace saved
- [ ] Minimal test case created (if possible)
- [ ] Environment details recorded
</reproduction-checklist>
</step>

<step id="3" title="Root cause investigation">
<instructions>
1. **Spawn git-historian**: Find related changes
2. **Query similar failures**: Search APEX patterns for matches
3. **Trace data flow**: Follow bad value to its source
4. **Form hypotheses**: Based on evidence (MAX 3 concurrent)
</instructions>

<spawn-agents>
<agent type="apex:git-historian">
**Scope**: [Suspected files/directories]
**Window**: 30 days (recent changes)
**Focus**: Commits that touched error location

Find: Recent changes, regressions, related fixes.
Return: Git intelligence with blame and commit analysis.
</agent>
</spawn-agents>

<mcp-calls>
```javascript
// Search for similar failures in pattern database
apex_patterns_discover({
  query: "[error symptoms]",
  filters: { types: ["ANTI", "FAILURE"] },
  max_results: 10
})

Copy### 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):

Copygit 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

Copy</validation-commands>

<mcp-checkpoint>
```javascript
apex_task_checkpoint(taskId, "DEBUG: Fix implemented and validated", 0.8)

Patterns

• Used: [Patterns that helped, with outcomes]
• Discovered: [New failure modes or fixes]

Learnings

• [Key insight 1]
• [Key insight 2]

Copy</reflection-template>

<mcp-calls>
```javascript
// Submit debugging reflection
apex_reflect({
  task: { id: taskId, title: "[task title]" },
  outcome: "success", // or "partial" or "failure"
  claims: {
    patterns_used: [
      {
        pattern_id: "[PAT:ID]",
        evidence: [
          {
            kind: "git_lines",
            file: "[file]",
            sha: "HEAD",
            start: 1,
            end: 10
          }
        ],
        notes: "[how it helped]"
      }
    ],
    trust_updates: [
      {
        pattern_id: "[PAT:ID]",
        outcome: "worked-perfectly" // or "worked-with-tweaks", "failed-completely"
      }
    ],
    learnings: [
      { assertion: "[What we learned]", evidence: [...] }
    ],
    // Only if genuinely new pattern discovered:
    new_patterns: [
      {
        title: "[Pattern title]",
        summary: "[What it does]",
        snippets: [
          {
            snippet_id: "[snippet id]",
            source_ref: {
              kind: "git_lines",
              file: "[file]",
              sha: "HEAD",
              start: 1,
              end: 10
            }
          }
        ],
        evidence: [...]
      }
    ]
  }
})

// Complete task if appropriate
apex_task_complete({
  id: taskId,
  outcome: "success",
  key_learning: "[Most important takeaway]",
  patterns_used: ["[PAT:IDs]"]
})

Copy<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>[APEX 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>