Navin debug agent: proven root cause, isolated branch and HTML report

Navin's debug agent does not shotgun-patch: it locks the signal, reproduces the bug, proves the root cause with evidence, isolates the work on a branch, then delivers an HTML report with numbered fix choices. You say #1, the agent fixes. No guessing.

When to use it

When something is broken and you want the root cause with proof: failing test, stack, status code, bad field, SQL query, flaky behaviour. Not for "improve the code a bit".

How to start

• Debug mode + free text (prefixed as /debug).
• /debug [signal|path|scope].
• Actions → Debug when available.

The model role is deep (UI mode debug). The dedicated tool is debug_repair.

The process, step by step

1. Lock the signal - exact error, failing test, stack, status code, bad field/query, or repro steps. Otherwise: git status / diff, recent logs, package scripts.
2. Reproduce with exec - failing test, typecheck, lint, or broken command. Capture stdout/stderr/exit codes. For SQL: schema / queries / migrations. For API: handler → validation → DB. For frontend: props/state → network → server.
3. Inspect - debug_repair(action=mcp_status): if DebugMCP is up (preset debugmcp → http://127.0.0.1:3001/mcp), breakpoints / variables / evaluate; else logs / pdb. Real evidence only.
4. Isolate - debug_repair(action=start_branch) before any code edits.
5. Narrow - read_file, git blame/diff, logs, metrics; the smallest instrumentation that proves the cause. Watch races, bad caching, wrong env, flaky tests, N+1, connection leaks, timeout/retry storms.
6. Board - file each confirmed defect (status=fix) when the project board is in use.
7. Close with debug_repair(action=report, …): debug-report-[date].html opens automatically (root cause + evidence, latent bugs, #N choices). Ask which # to start.

Apply code only if asked; otherwise the agent may switch to Agent and point to /forge after you choose.

What the report contains

Same pattern as Review and Security: self-contained HTML (inline CSS, no external JS), executive summary, root-cause evidence, latent bugs found along the way, numbered fix plan (effort, risk if delayed, first step). Chat stays short: 3 to 6 sentences + "Start with #1?".

Debug vs feeling-based patches

Debug + board + autonomy

Findings become tasks. With board autonomy: navin/task-* branch, green tests, PR, issue closed. The root cause does not die in the chat.

FAQ

Do I need DebugMCP?

No. Without MCP, the agent uses logs, pdb, tests and code reading. With MCP, live breakpoints and evaluate speed things up.

Does the agent fix everything alone?

No by default. It proves, reports, and waits for your number. Auto-fix only if you ask.

How is it different from Agent mode?

Agent implements. Debug proves first. Chain them: Debug → pick #1 → Agent / /forge.

Download Navin · Features · Documentation

Recommended next reads

• Expert review → review agent
• AppSec audit → security agent
• Full cycle → Code module
• Delivery pipeline → autonomous board

Conclusion

A debug that locks the signal, reproduces, proves, isolates and delivers a numbered plan: that is the end of random patches, and the start of a pipeline where every bug has evidence before a fix.