---
name: debugging
description: Use when tests fail, exceptions occur, or behavior is non-deterministic, especially after 2+ failed manual fix attempts
effort: medium
---

# Debugging Skill

Delegates to the **debugger** agent.

## Model Selection

Default: **sonnet**. Escalate via `model` parameter on the Agent tool:

| Task Shape | Model | When |
|-----------|-------|------|
| Single test failure, clear stack trace | sonnet (default) | Most debugging |
| Multi-component, non-deterministic, or cross-module | opus | Flaky tests, race conditions, system-level |

## Code Navigation

**REQUIRED SUB-SKILL:** Use **nx:serena-code-nav** for all symbol-level navigation during debugging. Serena gives accurate call traces; Grep finds text matches that may be comments or strings.

- **Trace call chains**: `find_referencing_symbols` on failing methods to find all callers
- **Find exception sources**: `find_symbol` on exception types to locate definitions
- **Understand type hierarchies**: `type_hierarchy` for polymorphic call resolution
- **Class/method inventory**: `get_symbols_overview` before reading a file

### Debugging Workflow
```
1. Identify failing test/exception
2. find_symbol on failure point — locate definition
3. find_referencing_symbols to trace all callers
4. type_hierarchy for polymorphic dispatch questions
5. Form hypothesis based on Serena evidence
6. Validate with `mcp__plugin_nx_sequential-thinking__sequentialthinking`
```

## When This Skill Activates

- Test failures after 2-3 fix attempts
- Exceptions with unclear causes
- Non-deterministic or flaky test failures
- Performance issues requiring systematic investigation
- Any bug where the root cause is not immediately obvious

## Pre-Dispatch: Seed Link Context

Before dispatching the debugger agent, seed T1 scratch with link targets so the auto-linker can create catalog links when the agent stores findings:

1. If the task references an RDR (pattern `RDR-\d+`), resolve it: `mcp__plugin_nx_nexus-catalog__search(query="RDR-NNN")`
2. Check T1 scratch for `rdr-planning-context`
3. Write link context to scratch:
   ```
   mcp__plugin_nx_nexus__scratch(action="put", content='{"targets": [{"tumbler": "<resolved-tumbler>", "link_type": "relates"}], "source_agent": "debugger"}', tags="link-context")
   ```
4. If no RDR/document reference found, skip seeding (the auto-linker handles empty context gracefully)

## Agent Invocation

Use the Agent tool to invoke **debugger**:

```markdown
## Relay: debugger

**Task**: [what needs to be done]
**Bead**: [ID] or 'none'

### Input Artifacts
- Files: [relevant files]

### Deliverable
Root cause analysis with fix recommendation

### Quality Criteria
- [ ] Root cause definitively identified with evidence
- [ ] Fix proposed and validated
- [ ] Hypothesis chain preserved
```

For full relay structure and optional fields, see [RELAY_TEMPLATE.md](../../agents/_shared/RELAY_TEMPLATE.md).

## Debugging Methodology

The debugger uses `mcp__plugin_nx_sequential-thinking__sequentialthinking`:
1. Form initial hypotheses about root cause
2. Identify evidence needed to validate/refute each hypothesis
3. Gather evidence from code, tests, logs
4. Evaluate - does evidence support hypothesis?
5. If refuted, branch to new hypothesis
6. When confirmed, propose fix with explanation

## Success Criteria

- [ ] Root cause definitively identified with evidence
- [ ] Fix proposed and validated
- [ ] Findings stored in nx store with title `debug-{component}-{issue-type}`
- [ ] Bead updated with resolution
- [ ] Hypothesis chain preserved in T2 for future sessions

## Agent-Specific PRODUCE

Outputs generated by the debugger agent:

- **T3 knowledge**: Root cause analysis via store_put tool: content="# Debug: {issue}\nRoot cause: {cause}", collection="knowledge", title="debug-finding-{issue}", tags="debug" and prevention patterns via store_put tool: content="# Prevention: {topic}\n{pattern}", collection="knowledge", title="pattern-prevention-{topic}", tags="pattern,prevention"
- **T2 memory**: Debugging journal via memory_put tool: content="content", project="{project}", title="debug-journal.md"; hypothesis chain via scratch_manage tool: action="promote", entry_id="<id>", project="{project}", title="debug-hypothesis-chain.md"
- **T1 scratch**: Hypothesis chain via scratch tool: action="put", content="Hypothesis {N}: {description}\nEvidence: {evidence}\nStatus: testing", tags="debug,hypothesis-{N}" (promoted to T2 when root cause found)

**Session Scratch (T1)**: Agent uses scratch tool for ephemeral working notes during the session. Flagged items auto-promote to T2 at session end.
