Root Cause Analysis from Stack Trace and Logs

Turns an error report, stack trace, and logs into ranked root-cause hypotheses. Includes the cheapest checks to confirm each one, a fix proposal, and a regression test plan.

You get: Situation summary, facts vs assumptions and timeline table

More like this

The prompt

root-cause-analysis-from-stack-trace-and-logs.md
Role: You are a senior {language} debugging specialist working on {service_name}.Context: The user must decide what to investigate first and whether a hotfix or a rollback is needed. You cannot run code or access systems. Reason only from the supplied evidence.
Task: Produce ranked root-cause hypotheses, a verification plan, and a fix recommendation.

Inputs:
- Symptom and impact: {symptom}
- Stack trace or error message: {stack_trace}
- Relevant logs with timestamps: {logs}
- Recent changes (deploys, config, dependencies): {recent_changes}
- Environment and versions: {environment}
- Relevant code: {code_snippet}
- Reproduction steps, if known: {repro_steps}

Workflow:
1. Restate the symptom, the scope (who or what is affected), and the first known occurrence.
2. List missing information and the single most valuable piece to obtain first.
3. State assumptions separately from observed facts.
4. Build a timeline from the logs and recent changes.
5. Propose 3 to 5 hypotheses. For each, give the supporting evidence, the contradicting evidence, a likelihood (High, Medium, or Low), and the fastest check that would confirm or reject it.
6. Recommend the most likely fix, a mitigation if the fix is not immediate, and a rollback criterion.
7. Design regression tests that would have caught this.

Constraints:
- Do not present a hypothesis as confirmed without evidence.
- Do not suggest broad rewrites. Prefer the smallest safe change.
- Flag any step that touches production data or needs elevated access.
- Avoid including secrets or personal data in any example.

Output format:
1. Situation summary.
2. Facts vs assumptions (two lists).
3. Timeline table: Time, Event, Source.
4. Hypothesis table: Rank, Hypothesis, Evidence for, Evidence against, Likelihood, Verification check.
5. Recommended fix with a code sketch under 25 lines.
6. Mitigation and rollback decision.
7. Regression test checklist.
8. Next actions: ordered, with time estimates as ranges.

Acceptance criteria:
- Each hypothesis maps to at least one specific line or log entry from the inputs.
- The verification checks are runnable by the user without guesswork.
- The fix addresses the top hypothesis and states its side effects.
- Missing information is explicit and prioritized.

Quality checks:
- Check that the timeline is consistent with the supplied timestamps.
- Check that the ranking reflects the evidence and not plausibility alone.
- Check that no unverified claim is worded as fact.
- Check that the regression tests cover the failure path.

Tool notes: In ChatGPT or Claude, paste logs in fenced blocks and trim them to the window around the first failure. In Cursor, reference the files in the stack trace with @file so the model reads the real code.

Example output

AI-written example

1. Situation summary
invoice-api (Python 3.11, FastAPI, SQLAlchemy 2.0): about 18% of POST /invoices calls return 500, starting 14:07 UTC, six minutes after deploy v2.31.0. The error is QueuePool limit of size 10 overflow 5 reached.

2. Facts vs assumptions

  • Facts: GET routes are healthy. v2.31.0 added apply_tax_rules() (tax.py:58), which opens its own session. Errors began 14:07:42.
  • Assumptions: traffic is unchanged. The session leaks on the exception path.
  • Missing, in priority order: (1) pool checked-out count over time, (2) the tax.py code after line 70, (3) request rate.

3. Timeline

TimeEventSource
14:01:10v2.31.0 deployeddeploy log
14:05:03TaxRuleError: unknown region 'XK'app log
14:07:42First pool TimeoutErrorapp log
14:09:15p95 latency 30s (pool timeout)metrics

4. Hypotheses

#HypothesisForAgainstLikelihoodCheck
1Session in apply_tax_rules isn't closed when TaxRuleError is raisedThe TaxRuleError at 14:05 precedes the pool errors, and tax.py:58 uses a bare Session()Leak rate not yet measuredHighRun SELECT count(*) FROM pg_stat_activity WHERE state='idle in transaction' AND application_name='invoice-api' (read-only, needs DB read role)
2Pool size too small for new loadPool is 10+5Only POST is affectedLowCompare request rate before and after the deploy
3Slow tax lookup holds connectionsLatency spike at 14:09Latency rose after the errors beganMediumCheck the tax query duration in the slow-query log

5. Recommended fix (addresses #1; side effect: sessions now roll back on error, so partial tax writes are discarded)

# billing/tax.py
def apply_tax_rules(invoice):
    with Session() as session:      # was: session = Session()
        rules = session.execute(select_rules(invoice.region)).all()
        if not rules:
            raise TaxRuleError(invoice.region)
        return compute(invoice, rules)

6. Mitigation and rollback
Mitigation: restart the pods to release connections (a temporary

Generated from this prompt by AI. Your results will vary.

Tips and common edits

Redact secrets, tokens, and personal data from logs before pasting. Include at least a 10-minute log window around the first failure. If the top hypothesis fails its verification check, rerun the prompt with the new result added to the inputs.

Questions about this prompt

More in Coding

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Explain This Error with Ranked Causes

Explains an error and stack trace in plain words, ranks the three most likely causes and gives a confirming check for each.

Pull Request Review with Merge Recommendation

Reviews a diff against your standards and returns a merge, merge-with-changes, or do-not-merge recommendation. Findings are ranked by severity, with evidence, suggested fixes, and open questions.

Unit Test Plan and Test Code for an Existing Function

Builds a behavior-based test matrix for a function or module and then generates test code in your framework. Covers edge cases, failures, and mocking boundaries, with coverage gaps stated honestly.

Debug an Error From the Message and the Code Around It

Finds the most likely cause of an error from the message and the relevant code, ranks other possible causes, and gives the smallest fix plus a way to prove it worked.

Architecture Decision Record for a Technology Choice

Compares realistic options against your constraints and produces a decision record. The record has a weighted comparison, risks, a reversal plan, and a recommendation the team can approve or challenge.

Regex with Match and Non-Match Test Strings

Writes a regex for your pattern, explains each part and provides 8 strings that should match and 8 that should not.

SQL Query from Schema and Question

Writes a SQL query that answers your question from your schema, explains each clause and suggests indexes worth adding.

Cursor .mdc Rules to Portable AGENTS.md Converter

Converts your pasted Cursor .mdc rules into a single AGENTS.md that Codex, Copilot and Gemini CLI can read, plus a table of what does not carry over.

Edge-Case Test Suite for One Function in Your Existing Test Framework

Writes tests for a single function that cover normal inputs, boundaries, bad input and error paths, in the test framework your project already uses.