# Debugging with Hermes AI: A Systematic Approach to Troubleshooting Code
You know the feeling. Your tests fail. The stack trace is 40 lines deep. The error message says something about a `NoneType` that shouldn't exist. You've been staring at the same function for 20 minutes and it *looks* fine.
This is where most developers spin their wheels — adding print statements, commenting out code, changing things at random hoping something sticks.
Hermes AI takes a different approach. It doesn't just dump code at you. It follows a structured debugging methodology that mirrors how senior engineers actually solve problems: reproduce, isolate, hypothesize, verify, fix.
Here's how to use it effectively.
The Debugging Skill: Your First Line of Defense
Hermes ships with a built-in `systematic-debugging` skill. When you hit a bug, you don't need to describe it perfectly — just point the agent at the failure and say "debug this."
``` > The test suite is failing on test_user_permissions. Debug it. ```
The skill kicks in automatically. It follows a clear sequence:
1. Reproduce — Run the failing test or command and capture the actual output 2. Isolate — Determine the minimum scope where the bug occurs (which module, which function, which line) 3. Hypothesize — Form 2–3 likely root causes based on the evidence 4. Verify — Test each hypothesis by reading the relevant code, checking logs, or running targeted queries 5. Fix — Apply the minimal change that resolves the root cause 6. Confirm — Re-run the test suite to verify the fix didn't break anything else
That last step is the one most developers skip. And it's the one that turns a "fix" into a *reliable* fix.
Live Debugging with debugpy
Sometimes a failing test isn't enough context. You need to see what's happening *at runtime* — watch variables change, inspect object state, step through execution.
Hermes includes a `python-debugpy` skill that starts a live debug server you can connect to from any DAP-compatible client (VS Code, PyCharm, or even a raw terminal).
``` > Start a debugpy server on port 5678 and set a breakpoint in auth/permissions.py line 42 ```
The agent will:
1. Inject `debugpy` into your process 2. Set breakpoints at the locations you specify 3. Wait for you to attach a debugger client 4. Optionally inspect variables and report back
This is particularly useful for:
- Race conditions that only show up under load - State corruption that happens deep in a request pipeline - Third-party library behavior you need to observe, not just read
Subagent Triage: Parallel Debugging
Here's where Hermes gets genuinely powerful. When you're facing a complex bug with multiple possible causes, you can delegate parallel investigation to subagents.
``` > The payment processing pipeline is failing intermittently. > Delegate one subagent to check the database connection pool, > another to review the Stripe API error logs, and a third to > inspect the queue worker configuration. ```
Each subagent gets its own terminal session and context window. They investigate in parallel — no sequential context pollution. When they finish, they report back their findings, and you (or the orchestrating agent) synthesize the results into a single diagnosis.
This pattern — which the subagent delegation skill calls "research and triage" — turns a 2-hour debugging session into a 15-minute parallel investigation.
Pattern: The Bug Report Workflow
For teams, I recommend standardizing on a bug report template that works with Hermes's debugging skill. Here's what I use:
```markdown ## Bug: [Short title]
Symptom: What's the observable failure? Repro steps: Exact commands or actions to trigger it Expected: What should happen Actual: What happens instead Environment: OS, Python/Node version, dependency versions Recent changes: What changed last (deployment, config, dependency bump) ```
When you feed this into Hermes:
``` > Here's a bug report. Debug it systematically: > [paste the report] ```
The agent has everything it needs — reproduction steps, environment context, and a timeline of recent changes. No back-and-forth clarification needed.
Pattern: Regression Hunting
When a previously working feature breaks, the fastest path is usually `git bisect`. Hermes can automate this:
``` > The user export feature broke sometime in the last 50 commits. > The test at tests/test_export.py passes on v2.3.0 but fails on main. > Run git bisect to find the breaking commit. ```
The agent will:
1. Set up the bisect range 2. Run the test at each checkpoint 3. Narrow down to the exact commit 4. Show you the diff and explain *why* it broke
This takes 5 minutes instead of an hour of manual binary search.
Common Pitfalls
A few things I've learned debugging with Hermes:
- Don't give it the answer. If you say "I think it's the database connection," the agent will anchor on that hypothesis. Describe the *symptom*, not your theory. - Run the failing test first. The debugging skill works best when it can see the actual error output. Let it reproduce the failure before you explain what you've tried. - Use subagents for breadth, not depth. Parallel investigation is for covering multiple possible causes, not for deep-diving into one theory. Give each subagent a narrow, distinct scope. - Verify after every fix. The temptation is to fix and move on. The debugging skill always includes a verification step — let it run. A "fix" that breaks three other things is worse than the original bug.
When to Use What
| Scenario | Approach | |----------|----------| | Single failing test | `systematic-debugging` skill | | Intermittent failure | `python-debugpy` with live breakpoints | | Multiple possible causes | Subagent triage (parallel investigation) | | Regression in recent commits | Automated `git bisect` | | Complex multi-service bug | Subagent triage + debugpy on suspect services |
The Meta-Lesson
The real productivity gain isn't that Hermes fixes bugs faster — it's that it prevents the *time waste* of unstructured debugging. The skill forces a discipline: reproduce before hypothesize, verify before move on.
That discipline is the difference between a 2-hour rabbit hole and a 15-minute fix. And it's the same discipline every senior engineer uses, just systematized and enforced by the agent.
Use the skill. Trust the process. Ship the fix.
---
*This post is part of the Liam's Landing series — practical engineering content from the terminal, by someone who lives there. Catch up on [Getting Started with Hermes AI](/blog/getting-started-with-hermes-ai-terminal-coding-partner), [Building Custom Skills](/blog/building-custom-hermes-ai-skills), [Automating with Cron Jobs](/blog/automate-your-dev-life-with-hermes-ai-cron-jobs), and [Subagent Delegation Patterns](/blog/subagent-delegation-patterns-hermes-ai).*