# Agents and skills for debugging and error diagnosis

> Find the root cause: stack traces, logs, incidents and memory leaks.

- Source: https://doutorai.pt/en/for/debugging
- Site: Doutor AI (https://doutorai.pt/en) - AI tools for small businesses

A bug rarely arrives with a label. It arrives as a test that fails only in continuous integration, a request that returns a 500 error once in every thousand, or memory that grows overnight until the process dies. The hard part is not writing the fix. It is proving which of ten plausible hypotheses is right before you touch the code.

The components on this page give Claude Code a method instead of guesses: reproduce first, read the stack trace from the bottom up, correlate logs across services, isolate the change with git bisect and only then propose the fix. Some investigate several hypotheses in parallel and cite file and line as evidence. Others connect the session to real production data in Sentry, Grafana or Datadog.

Start with the simplest option. If the error is local and reproducible, a method skill plus a debugger agent are enough for most cases. If the problem only happens in production, you need access to the evidence, so install the connector for the tool you already use first. Parallel investigation and incident commands make sense when the cost of downtime is high.

21 hand-picked components, from 4 different angles.

## Investigation method and root cause

Components that impose an order on the diagnosis: reproduce, form hypotheses, gather evidence and only then fix. This is where you start.

- **debugger** (Agents): Takes the concrete error, logs and stack trace included, and works until it identifies the root cause instead of suggesting a fix based on the visible symptom. [page](https://doutorai.pt/en/components/agents__debugger)
- **systematic-debugging** (Skills): Works as a brake: it applies as soon as a bug, a test failure or unexpected behavior appears, and it kicks in before any fix is proposed. [page](https://doutorai.pt/en/components/skills__systematic-debugging)
- **debug-error** (Commands): Walks through the complete methodology step by step, from collecting the error message and building a minimal reproducible case to reading the stack trace from the bottom up. [page](https://doutorai.pt/en/components/commands__debug-error)
- **parallel-debugging** (Skills): A good fit for bugs with several possible causes and no obvious one: it raises competing hypotheses, investigates them in parallel and decides which one survives the evidence. [page](https://doutorai.pt/en/components/skills__wshobson-agents__parallel-debugging)
- **team-debugger** (Agents): Each instance investigates a single hypothesis and returns evidence with file and line, plus a confidence level. It helps the team separate facts from assumptions. [page](https://doutorai.pt/en/components/agents__wshobson-agents__agents-team-debugger)
- **gsd:debug** (Skills): Keeps the state of the investigation even when the session context is reset, which matters for bugs that take hours or several days to close. [page](https://doutorai.pt/en/components/skills__davepoon-subagents__debug)

## Logs, stack traces and production data

For when the error only happens on the server and the only evidence available is logs, metrics and traces. Here the limitation is usually access to the data, not the reasoning.

- **error-detective** (Agents): Correlates errors across services instead of looking at one at a time, which helps when the failure visible in one place originates somewhere completely different. [page](https://doutorai.pt/en/components/agents__error-detective)
- **devops-troubleshooter** (Agents): Covers the operational side, with log analysis, deployment failures and monitoring configuration, for when suspicion falls on the infrastructure rather than the application. [page](https://doutorai.pt/en/components/agents__devops-troubleshooter)
- **Context** (Commands): Reads error messages, stack traces and failure patterns to get to the cause, and suggests, besides the fix, the observability steps that were missing. [page](https://doutorai.pt/en/components/commands__wshobson-agents__commands-smart-debug)
- **sentry** (Connectors): The Sentry MCP connector, designed for coding workflows with human supervision. It gives the session access to the errors already recorded, instead of you having to describe them by hand. [page](https://doutorai.pt/en/components/mcps__sentry)
- **grafana** (Connectors): Connects Claude Code to Grafana dashboards and monitoring, on your own instance or on Grafana Cloud, so you can check the state of the system during the investigation. [page](https://doutorai.pt/en/components/mcps__grafana)
- **datadog-cli** (Skills): Searches logs, queries metrics and follows request traces from the Datadog command line. It makes sense for anyone who already has their observability concentrated in that tool. [page](https://doutorai.pt/en/components/skills__datadog-cli)

## Production incidents and post-incident analysis

With the system down, the problem is no longer just technical: you need to classify severity, coordinate the response and record afterwards what you learned.

- **incident-responder** (Agents): Made for the moment production goes down: it coordinates the debugging, applies the fix and leaves the post-mortem documented instead of putting it off indefinitely. [page](https://doutorai.pt/en/components/agents__incident-responder-2)
- **incident-commander** (Skills): Brings the complete SRE framework, with severity classification, timeline reconstruction and post-incident review. It also helps set up on-call rotations for a new service. [page](https://doutorai.pt/en/components/skills__alirezarezvani-claude-skills__incident-commander)
- **postmortem-writing** (Skills): Writes blameless post-mortems, with root cause, timeline and concrete actions. It is the piece that keeps you from repeating the same incident within three months. [page](https://doutorai.pt/en/components/skills__wshobson-agents__postmortem-writing)
- **pagerduty-incident-responder** (Agents): For teams that already get alerts through PagerDuty: it cross-references the incident context with recent code changes and proposes the fix as a pull request on GitHub. [page](https://doutorai.pt/en/components/agents__pagerduty-incident-responder)

## Regressions, flaky tests and memory leaks

Three families of bugs with their own diagnosis, where the question is not what is wrong, but since when, or where the memory is getting stuck.

- **git-bisect-helper** (Commands): Runs automated git bisect sessions with a test run at each step, to answer the question of which commit caused the failure. [page](https://doutorai.pt/en/components/commands__git-bisect-helper)
- **test-runner** (Agents): Runs the suite, reads the results and diagnoses the cause of the failures, delivering concrete fixes instead of a report full of red tests. [page](https://doutorai.pt/en/components/agents__test-runner)
- **Test Debugger Agent** (Agents): Specialized in flaky or failing Playwright tests, with a systematic taxonomy that separates a badly written test from a real bug in the application. [page](https://doutorai.pt/en/components/agents__alirezarezvani-claude-skills__agents-test-debugger-09996b)
- **performance-profiler** (Agents): Tackles performance bottlenecks and memory leaks with load tests and monitoring, for when the application does not crash but keeps degrading over the course of the day. [page](https://doutorai.pt/en/components/agents__performance-profiler)
- **optimize-memory-usage** (Commands): Leak detection, garbage collection tuning and memory profiling brought together in a single command. It applies when the process grows until it has to be restarted. [page](https://doutorai.pt/en/components/commands__optimize-memory-usage)

## How to install and where each piece fits

Agents, skills and commands are Markdown files that live in your repository, inside .claude/agents/, .claude/skills/ and .claude/commands/. Copy the file to the right folder and Claude Code recognizes it in the next session: agents and skills are triggered by their description, commands are invoked with a slash. MCP connectors work differently, they need an entry in the configuration file and their own credentials, for example the instance URL and a service account token in the case of Grafana. Start with a debugger agent and a method skill. Add connectors only when you really need production data inside the session.

## A working order that avoids blind fixes

The order matters more than the tool you choose. First reproduce: without a minimal case that fails consistently, any fix is a guess. Then gather the evidence: the full stack trace, the logs from before and after the error, the environment where it happens. Only then form hypotheses, and if there is more than one plausible hypothesis it is worth investigating them in parallel instead of testing them one after another. If the problem is recent and the old code worked, bisect gives you an answer faster than reading the code. The fix comes last, together with a test that used to fail and now passes.

## Limits of what these components can see

None of these components sees what it is not given. A debugger agent works on the code, logs and tests it has access to. If the error only shows up with real data or under load, you will need to connect the session to your observability tool or reproduce the scenario locally. MCP connectors also raise the question of access: a Sentry or Grafana token gives read access to sensitive information, so use service accounts with minimal permissions. And always be wary of a root cause presented without evidence; ask for the file, the line and the test that confirms it.

## Keep reading

- [Debugger Agent](https://doutorai.pt/en/how-to/subagents--debugger)
- [Checkpoints and Rewind](https://doutorai.pt/en/how-to/checkpoints)

## Frequently asked questions

### What is the difference between a debugger agent and a debugging skill?

The agent is an executor with its own context: it receives the problem, investigates and returns a diagnosis. The skill is knowledge that changes the way Claude Code approaches the task, for example by making it reproduce the error before proposing fixes. In practice they are used together: the skill defines the method and the agent does the work.

### Do I really need an MCP connector to debug?

Not if the bug is reproducible on your machine. Connectors such as Sentry, Grafana or Datadog pay off when the evidence is outside the repository, in recorded errors, metrics or production traces. They require credentials and configuration, so add them when missing data is really what is holding you up.

### How should I handle a test that fails intermittently?

Treat it as a bug, not as noise. An agent dedicated to flaky tests classifies the failure before fixing it: it may be a badly written wait, a dependency between tests, shared state or a real race condition in the application. Rerunning the test until it passes hides the problem instead of solving it.

### Is it worth investigating several hypotheses at the same time?

It is when the cost of downtime is high and there are plausible causes in different areas, for example the database, the cache and the network. Each investigation gathers evidence to confirm or rule out its hypothesis and at the end the results are compared. For a small, well-located bug it is too much work.

### What is worth keeping after resolving an incident?

The timeline, the root cause, the real impact and the actions still to be done. A blameless post-mortem is what turns a bad night into reusable material and serves as the basis for the runbook next time. Without that record, the same failure comes back and the investigation starts again from scratch.

---
Content by Doutor AI (https://doutorai.pt/en). When quoting, please cite the source: https://doutorai.pt/en/for/debugging