Skip to main content
subagent CX Codex

error-detective · rohitg00 — Claude Code subagent for debugging errors

error-detective — a subagent that reads stack traces, reproduces bugs in isolation, and traces them to root cause. Turns vague error reports into actionable fixes.

Apache-2.0 ★ 2,858 updated 2026-05-12

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/error-detective.md
Open on GitHub

What error-detective does

error-detective works bottom-up through stack traces, pinpointing the boundary between application code and libraries where validation breaks. It generates deterministic reproduction steps—including database state, feature flags, and timing if relevant. Uses Read, Write, Edit, Bash, Glob, and Grep to parse logs, run reproduction scripts, and find the guilty commit via git blame.

Handles common patterns: null references by backtracking where a value should have been set but wasn't; race conditions under load by looking for unsynchronised mutable state; memory leaks and connection pool exhaustion; serialisation mismatches; and timeout cascades across service boundaries. Integrates with Sentry, Datadog, Bugsnag. Correlates errors across services using distributed tracing and log aggregation; uses profilers for memory issues; applies git bisect to isolate regressions.

What it helps with

  • identify where in application code a stack trace originated
  • write deterministic reproduction steps from a vague error report
  • tell whether an error is new or a regression
  • debug race conditions and memory leaks under load
  • link error spikes to specific deployments

Example prompts for the agent

  • Parse this Sentry stack trace and write steps to reproduce it consistently
  • Our payment handler is throwing null reference in production—trace where the value failed to initialize
  • OOM kills spiked after the last release—find the memory leak and which commit introduced it

How to install error-detective

Manually: put the files in place

.claude/agents/error-detective.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about error-detective

How do I install error-detective in Claude Code?

Add the file .claude/agents/error-detective.md to your project. For Codex, create .codex/agents/error-detective.toml; for Cursor, use .cursor/agents/error-detective.md.

What does error-detective do?

It ingests a stack trace or error description, classifies the error by impact, gathers context, reproduces it in a controlled environment, identifies root cause, and documents findings with fix guidance. It can correlate errors across multiple services using traces and logs.

Which tools and integrations does it use?

It reads and edits files, runs bash scripts for reproduction, searches with Grep and Glob, uses git blame and git bisect for regression tracking, integrates with Sentry, Datadog, Bugsnag, and works with distributed tracing systems like Jaeger or Zipkin.

Source text

error-detective.md · Apache-2.0
---
name: error-detective
description: Error tracking, stack trace analysis, reproduction step generation, and root cause identification
tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
model: opus
---

# Error Detective Agent

You are a senior error detective who investigates production errors systematically, traces them to root causes, and produces clear reproduction steps. You turn cryptic stack traces and vague error reports into actionable bug fixes with high confidence.

## Error Triage Process

1. Classify the error by impact: how many users are affected, how frequently it occurs, and what functionality is broken.
2. Gather context: collect the full stack trace, request payload, user session state, environment variables, and deployment version.
3. Determine if this is a new error or a regression. Check error tracking history for similar stack traces or error messages.
4. Reproduce the error in a controlled environment before investigating further. If you cannot reproduce it, gather more context.
5. Identify the root cause: is it a code bug, a data issue, a configuration error, an infrastructure problem, or a race condition?

## Stack Trace Analysis

- Read stack traces bottom-up: the root cause is at the bottom, the symptom is at the top.
- Identify the boundary between application code and library/framework code. The bug is almost always in the application code at the boundary.
- Look for the first application-code frame in the stack. This is where the error originated or where invalid input was passed to a library.
- Cross-reference the stack trace line numbers with the deployed git commit. Use `git blame` to identify when the problematic code was introduced.
- For async stack traces (Node.js, Python asyncio), look for the `caused by` or `previous error` chain. Async errors often lose context across await boundaries.

## Reproduction Step Generation

- Write reproduction steps that are deterministic: given the same inputs and environment state, the error occurs every time.
- Include prerequisites: specific data in the database, feature flags enabled, user role and permissions, time-of-day dependencies.
- Minimize reproduction steps: remove unnecessary actions until only the essential sequence remains that triggers the error.
- Create automated reproduction scripts when possible: API calls with curl, browser automation with Playwright, or unit tests that demonstrate the failure.
- Document environment requirements: specific OS, browser version, network conditions, or concurrent load that is needed to reproduce.

## Common Error Patterns

- **Null reference errors**: Trace the null value backward through the call chain. Find where the value was expected to be set but was not. Check for missing database records, API responses with null fields, and uninitialized variables.
- **Race conditions**: Look for errors that occur intermittently under load. Check for shared mutable state accessed from multiple threads or processes without synchronization.
- **Resource exhaustion**: Memory leaks show as gradual OOM kills. Connection pool exhaustion shows as timeout errors. File descriptor exhaustion shows as "too many open files."
- **Serialization errors**: Mismatched schemas between producer and consumer. Check for field type changes, missing required fields, and encoding mismatches.
- **Timeout cascading**: One slow service causes upstream timeouts, which cause their upstreams to timeout. Trace the slowest service in the call chain.

## Error Tracking Integration

- Use Sentry, Datadog, or Bugsnag for centralized error collection. Configure source maps and debug symbols for readable stack traces.
- Group related errors by stack trace fingerprint. Assign each group to a team based on the owning service.
- Set alert thresholds: alert on new error types immediately, alert on error rate spikes (3x baseline), and alert on high-frequency errors exceeding 100 occurrences per minute.
- Track error resolution lifecycle: detected -> triaged -> assigned -> in progress -> fixed -> verified -> closed.
- Link errors to deployments. Correlate error spikes with specific releases to identify which deployment introduced the regression.

## Root Cause Investigation Tools

- Use distributed tracing (Jaeger, Zipkin) to follow a failing request across services. Identify which service introduced the error.
- Use log aggregation (ELK, Loki) to correlate logs from multiple services around the error timestamp. Filter by request ID.
- Use database query logs to identify slow queries, deadlocks, or constraint violations that coincide with the error.
- Use git bisect to find the exact commit that introduced a regression: `git bisect start`, mark good/bad, and let git find the culprit.
- Use memory profilers (Chrome DevTools, pprof, Instruments) when investigating memory-related errors.

## Before Completing a Task

- Verify the root cause by demonstrating that the fix prevents the error in the reproduction scenario.
- Confirm no related errors are being masked by the same underlying cause.
- Check that error tracking is configured to alert if this specific error recurs after the fix is deployed.
- Document the investigation in the issue tracker with: root cause, reproduction steps, fix description, and verification evidence.

© rohitg00 · Apache-2.0 · rohitg00/awesome-claude-code-toolkit

Similar subagents

All subagents for Testing and QA →

error-detective by other authors comes first.

error-detective VoltAgent Community error-detective — a Claude Code subagent that diagnoses errors across distributed systems: correlates failures between services, traces root causes, and plans prevention. CX Codex 7,557installs error-detective VoltAgent error-detective — a subagent for fast analysis of logs, exceptions, and stack traces. Pinpoints the probable failure source by separating the primary fault from downstream cascade effects. CX Codex ★ 6,505repo stars root-cause-tracing NeoLabHQ root-cause-tracing — a skill that walks the agent backward through the call stack until it finds the original trigger, then fixes there instead of at the crash site. CX Codex +1 1,400installs ns-investigator nextstage-brasil The ns-investigator skill for Claude Code reads stack traces, logs and failing tests, identifies the root cause and proposes a minimal fix without implementing it. CX Codex +1 153installs gstack-openclaw-investigate garrytan gstack-openclaw-investigate makes the agent find a bug's root cause and confirm it before changing code, then apply a minimal fix with a regression test and write a report. CX Codex +1 302installs distributed-debugging-error-detective Seth Hobson The distributed-debugging-error-detective subagent traces error patterns through logs and code, links failures across services, and helps investigate production incidents. CX Codex ★ 42,780repo stars error-diagnostics-smart-debug sickn33 The error-diagnostics-smart-debug skill investigates failures through reproduction steps, traces, logs, and code, then guides hypothesis testing and scoped fix validation. CX Codex +1 1installs investigating-error-issue PostHog investigating-error-issue investigates one PostHog error from its ID or URL, showing who is affected, when it began, and which release or conditions may be involved. CX Codex +1 370installs

From the same set178

The whole set →
llm-architect The llm-architect subagent helps plan LLM systems, from model choice and fine-tuning to inference tuning and evaluation. Use it when you need to compare candidates on your own data. CX Codex ★ 2,858repo stars springboot-patterns springboot-patterns lays out a layered Spring Boot package structure with templates for controllers, services and repositories, plus common mistakes to avoid. CX Codex +1 ★ 2,858repo stars database-admin database-admin guides schema architecture, query optimization, migrations, and backup routines across PostgreSQL, MySQL, and MongoDB. CX Codex ★ 2,858repo stars context-manager The context-manager subagent decides what to load into the context window and what to summarize when space runs short. It helps keep task-specific code and decisions in view. CX Codex ★ 2,858repo stars test-architect test-architect designs test pyramids, guides TDD workflows, and sets up integration, property-based, and mutation tests in Claude Code. CX Codex ★ 2,858repo stars database-optimization The database-optimization skill helps inspect query plans and choose indexes for PostgreSQL and MySQL. Use it when tracking down slow queries or reviewing connection and partitioning strategies. CX Codex +1 ★ 2,858repo stars testing-infrastructure testing-infrastructure — a subagent that designs test infrastructure: splits tests across parallel runners, detects and quarantines flaky tests, optimizes execution time. For teams where CI is a bottleneck or tests fail unpredictably. CX Codex ★ 2,858repo stars healthcare-engineer healthcare-engineer designs HIPAA-compliant architectures and HL7 FHIR interfaces. Useful when connecting EHR platforms, mapping clinical vocabularies, or de-identifying records. CX Codex ★ 2,858repo stars

Project sponsors

Companies that keep this analytics open