Compatible with Cursor, Claude Code, Cline, Roo Code, Antigravity

Production Exception & Stack Trace Root-Cause Analysis

Systematic investigation workflow for diagnosing production exceptions and constructing verified patches.

DebuggingObservabilityLogsIncidentsBackend

v1.0.0 · Updated 2026-08

Skill Objective

Guide AI agents through hypothesis-driven incident analysis: analyze stack traces, reconstruct invalid state transitions, formulate verified hypotheses, and create regression tests.

Execution Workflow Procedure

Ordered steps the coding agent executes when performing this skill.

Error Classification & Frame Inspection

Locate the exact top-of-stack line number, exception type, and root cause cause chain in the stack trace.

Reconstruct State Invariants

Identify what variable or object was in an unexpected state (null, undefined, expired, locked) to trigger the error.

Formulate 2-3 Hypotheses

Formulate prioritized hypotheses for why the invalid state existed. Evaluate evidence from surrounding logs and code to confirm or eliminate each hypothesis.

Construct Patch & Regression Test

Write the defensive code fix and an automated test case reproducing the exact failure scenario.

Agent Safety Guardrails & Anti-Hallucination Rules

DO NOT merely add a surface null check without explaining why the variable was null.
DO NOT guess random fixes; demand evidence from logs or code paths.

Expected Output Format

Structured root cause analysis and verified patch.

🔍 Error Anatomy: Exact trigger line, exception type, and failing state.

💡 Hypothesis Evaluation: 2-3 hypotheses evaluated with evidence.

🛠️ Code Patch & Test: Defensive code fix and regression unit test.

Domain Verification Checks

Root Cause vs Symptom: Fixes the underlying state invalidity rather than suppressing errors.

Defensive Optional Handling: Implements clean Optional/Result patterns.

Automated Regression Test: Includes test reproducing the bug.

Example Agent Invocations

"Analyze this NullPointerException stack trace from our billing service and provide a fix."

"Investigate why this user profile endpoint is throwing 500 errors during guest checkout."

Install / Configure This Skill

# Place in .cursorrules or create .cursor/rules/production-exception-root-cause.mdc
# Trigger: Whenever you perform production exception & stack trace root-cause analysis

---
name: production-exception-root-cause
description: Diagnose production stack traces and error logs using hypothesis-driven investigation to produce verified bug fixes.
version: 1.0.0
compatibility: [Cursor, Claude Code, Cline, Roo Code, Antigravity]
---

# Production Exception & Stack Trace Root-Cause Analysis

## Objective
Analyze production error logs and stack traces to identify the systemic root cause, formulate verified hypotheses, and create defensive code patches.

## Workflow
1. **Frame Inspection**: Identify the exact line, method, and exception type from the stack trace.
2. **State Invariant Analysis**: Determine what invalid variable state or unhandled edge case triggered the exception.
3. **Hypothesis Testing**: Formulate 2-3 hypotheses and evaluate them against code paths and logs.
4. **Patch & Regression Test**: Deliver the defensive code fix alongside an automated test reproducing the incident.

Complementary Agent Prompt

Need a quick one-time prompt for chat?

Try the Production Exception & Stack Trace Root-Cause Analyzer — a lightweight version designed for 1-click copying directly into Claude, ChatGPT, or Cursor chat.

View Prompt