Debugging — From Symptom to Root Cause

From the free book Delta: Closing the Specification Gap (Dhuri, 2026). The PDF is the canonical edition — figures, tables, and code formatting are simplified online.

The XML Evidence Brief and the discipline that finds root causes before hypotheses

“The difference between a debugging session that takes two hours and one that takes two days is not luck. It is how much evidence you assembled before you started asking questions.” The Evidence Brief is structured so that filling it out almost always reveals the root cause before the prompt is even sent. A complete brief that fails to surface the problem is rare; an incomplete brief that produces no useful diagnosis is the common case. In This Chapter

1. Law 7: the Evidence Brief must be filled before you start debugging
2. The XML Evidence Brief: six sections, one outcome
3. The Rubber Duck Upgrade: questions before hypotheses
4. Domain-specific recipes: BigDecimal precision, EF Core transactions, N+1
5. Three illustrative incidents with financial quantification LAW 7 OF ENTERPRISE AI PROMPTING

The best debugging prompt is a complete Evidence Brief. Fill it before you start. Most developers open Claude or Copilot Chat and paste a stack trace with ‘help’. The model’s diagnostic quality is bounded by the evidence provided. The Evidence Brief forces you to gather the full trace, the code at the failure, recent changes, current metrics, and what you have already confirmed is NOT the cause. Filling that last section alone halves the search space.

PATTERN — The BigDecimal That Was Not

PATTERN-3383

A payments platform’s month-end reconciliation was off by $0.01 to $0.12 each run. Inconsistent, below automated alert thresholds, failed every quarterly audit. Three engineers investigated for two weeks: database corruption (no), network issues (no), timezone bugs (no).

THE COST OF THIS MISTAKE Incident: double accumulator in batch service: –0.010.12 per run, ,→ undetected for 5 months Total cost: $0.57 average per monthly run × 5 months + 2 weeks × 3 ,→ engineers investigation time ($~30,000) Time to resolve: 2 weeks (3 engineers), 30 minutes code fix Prevention: "BigDecimal.ZERO accumulator. .add() throughout. Never ,→ double in financial batch."

6.1 The XML Evidence Brief <role> Experienced SRE debugging a production incident. Distinguish confirmed facts from hypotheses. Flag every assumption about code you ’cant see. </role> <incident> <service>{{service name and one-line description}}</service> <env>{{production | staging | configuration details}}</env> <frequency>{{always | intermittent | under-load | since-deploy-X}}</ ,→ frequency> <impact>{{what users see | data risk | revenue impact | SLA breach ,→ }}</impact> </incident> <evidence> <stack_trace> {{full stack trace — replace PII with [REDACTED]}}</stack_trace> <code_at_failure> {{method at the top of the trace, –2040 lines}}</code_at_failure> <recent_changes> {{last deployment diff | config changes | ‘none in 72’h}}</ ,→ recent_changes> <metrics> Error rate: X% | P99 latency: Xms | CPU: X% | Memory: X%</metrics> </evidence> <already_ruled_out> {{specific things confirmed NOT the cause — this the highest-value ,→ section}} </already_ruled_out> <task> 1. Most likely root cause (one sentence) with reasoning from ,→ evidence only 2. Two alternative hypotheses ranked by likelihood 3. Specific diagnostic commands (exact — not ‘check the ’logs) 4. Proposed fix for the most likely cause </task>

6.2 The Rubber Duck Upgrade "I have a bug I ’cant isolate after two hours. Do NOT give hypotheses yet. SYMPTOM: [exact observed behavior — not my theory about the cause] EXPECTED: [what correct behavior looks like] RULED OUT: [confirmed non-causes, one per line] Ask me exactly SIX diagnostic questions. After I answer ALL six, give me your two most likely hypotheses. Do NOT give hypotheses before I answer the questions."

The six-question protocol surfaces the assumption you forgot to examine. That assumption is almost always the root cause. When you receive hypotheses first, you anchor on them. When you answer questions first, the assumption surfaces naturally — often before question four.

Key takeaways

• Law 7: fill the Evidence Brief before prompting. The act of filling <already_ruled_out> alone often reveals the root cause.
• The Evidence Brief has four parts: incident description, evidence (trace, code, changes, metrics), already-ruled-out, and task. All four every time.
• Rubber Duck Upgrade: six questions before hypotheses. This surfaces the forgotten assumption that is almost always the cause.
• BigDecimal precision failure signature: inconsistent discrepancy, high transaction volume, absent in unit tests. Diagnosis requires the Evidence Brief, not a stack trace.

TRY IT NOW

1. Assemble the Evidence Brief for your most recent production incident. What evidence took longest to gather? Build a pre-filled template for your system.
2. Apply the Rubber Duck Upgrade to a bug that has been open for more than a week. What surfaces in the answers?
3. Write domain-specific debugging recipes for the three most common production bug classes in your system.

UP NEXT — Chapter 7: Documentation That Gets Read

Most documentation describes what the code does. Chapter 7 shows you how to generate documentation that answers the question readers actually ask: when should I call this — and what happens when I do.

62