hellblazer/debugging

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:

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