debugging

Debugging Skill

Delegates to the debugger agent (model: opus).

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: jet_brains_find_referencing_symbols on failing methods to find all callers
• Find exception sources: jet_brains_find_symbol on exception types to locate definitions
• Understand type hierarchies: jet_brains_type_hierarchy for polymorphic call resolution
• Class/method inventory: jet_brains_get_symbols_overview before reading a file

Debugging Workflow

1. Identify failing test/exception
2. jet_brains_find_symbol on failure point — locate definition
3. jet_brains_find_referencing_symbols to trace all callers
4. jet_brains_type_hierarchy for polymorphic dispatch questions
5. Form hypothesis based on Serena evidence
6. Validate with `mcp__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

Agent Invocation

Use the Agent tool to invoke debugger:

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

Debugging Methodology

The debugger uses mcp__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="", 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.