Root cause tracing

Root Cause Tracing

Use this skill when an observed failure may be downstream from its real cause.

Goal

Increase debugging success rate by tracing from:

1. visible symptom
2. immediate failure point
3. upstream trigger path
4. first incorrect state, assumption, input, or code change

Do not jump to fixes before the likely root cause is evidence-backed.

Core Rules

1. Start from the observed symptom

Capture the concrete failure first:

• error message
• stack trace
• wrong output
• failing test
• UI misbehavior
• flaky or intermittent behavior

Use exact evidence when possible instead of paraphrasing.

2. Separate symptom from cause

The place where the app crashes or looks wrong is often not the true origin.

Always distinguish:

• symptom: what became visible
• failure point: where the system noticed or surfaced it
• trigger: what earlier action or state led there
• root cause: the earliest incorrect condition that explains the failure

3. Reproduce before theorizing

Before editing code, reproduce the problem as consistently as possible.

If the issue is flaky, capture:

• frequency
• environment
• recent changes
• timing or order dependencies
• inputs and state that seem correlated

4. Trace the narrowest path backward

Work backward from the failing surface by checking:

• call chain
• data flow
• state transitions
• function inputs/outputs
• config/env assumptions
• recent edits or commits

Avoid scanning the whole codebase without a hypothesis.

5. Prefer evidence over guesswork

For each hypothesis, look for confirming or disconfirming evidence.

Good evidence includes:

• stack traces
• logging
• failing tests
• minimal repros
• git diff/history
• runtime state inspection
• browser-visible behavior paired with code evidence

6. Patch the cause, not the symptom

Do not stop at a workaround unless the user explicitly wants a temporary mitigation.

Before fixing, ask:

• What earlier bad state or assumption caused this?
• If I patch only the visible error, will the bad state still exist?
• Can I write a regression test that proves the upstream cause is fixed?

Minis-Specific Workflow

Shell-first tracing

Use shell commands to:

• inspect project structure
• search for the failing symbol or message
• run targeted tests
• inspect logs and outputs
• compare recent file changes
• create tiny repro scripts if needed

Browser-assisted tracing

For web apps:

• reproduce the UI symptom in the browser
• map the visible symptom to route/component/state changes
• pair browser observations with code-level evidence
• do not rely only on visual inspection if code/test evidence is available

Git-aware debugging

If the issue may be regression-related, inspect:

• recent edits
• recent commits
• changed dependencies/config
• files near the failure surface

Prefer narrowing the suspect set before changing code.

Debugging Sequence

Use this order:

1. Restate the observed symptom.
2. Reproduce it.
3. Identify the failing surface.
4. Trace backward through the narrowest relevant path.
5. List 1–3 plausible root-cause hypotheses.
6. Gather evidence to eliminate weak hypotheses.
7. Identify the most likely root cause.
8. Only then propose or implement a fix.
9. Add or update a regression test when possible.

Common Root-Cause Buckets

Check whether the issue comes from:

• wrong input assumptions
• stale or malformed state
• incorrect ordering/timing
• missing edge-case handling
• invalid config/env expectations
• API contract mismatch
• incorrect data transformation
• recent refactor regression
• UI state and data state divergence
• error-handling that hides the first failure

Heuristics

Prefer:

• tracing upstream before editing
• one hypothesis at a time
• narrowing by evidence
• finding the first bad transition, not the loudest failure
• reproductions tied to concrete inputs and state

Be cautious when:

• the stack trace is noisy or indirect
• async behavior hides ordering issues
• logs only show downstream failures
• multiple recent changes overlap
• flaky tests tempt speculative fixes

Integration with Other Skills

• Use test-driven-development once the likely root cause is known and you want to lock the fix with the smallest failing test.
• Use agent-security-guard if debugging would involve secrets, uploads, installs, or risky system changes.
• Use prompt-injection-defense if the bug report, logs, or documentation come from untrusted external content.

Completion Checklist

Before calling the analysis done, check:

• Is the symptom clearly stated?
• Is the failure reproducible or at least bounded?
• Did you identify the failing surface?
• Did you trace at least one path upstream?
• Is the proposed root cause supported by evidence?
• Is it earlier than the visible symptom?
• Is there a regression test or repro to confirm the fix later?

Response Template

• Symptom:
• Reproduction:
• Failing surface:
• Upstream path traced:
• Leading hypotheses:
• Best-supported root cause:
• Evidence:
• Suggested next step:

Example Triggers

• "Trace this bug to the real root cause before fixing it."
• "Why is this test failing?"
• "Find the earliest cause, not just the crash site."
• "Help me debug this flaky behavior step by step."
• "Work backward from this error and tell me what actually broke first."