Debugging and Root Cause Analysis

Pathrule1 Rule • 2 Memories • 2 Skills

Debugging slows down when teams change several things at once, mistake correlation for cause, trust stale logs, or stop at the first local fix without explaining why the system entered the failing state. This pattern constrains evidence preservation, records hypothesis and reproduction decisions, and supplies separate rapid-triage and root-cause workflows for defects that cross code, data, timing, and environment boundaries. It differs from incident response by focusing on active defect diagnosis and causal proof; incident command, communications, and service restoration remain in the incident pattern.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

triage-software-defect

prove-root-cause-and-fix

src/

Change one causal variable at a time

docs/

debugging/

A symptom timeline narrows the causal search

Root cause explains mechanism and necessary conditions

Rules

Change one causal variable at a time/srchighstrictPreserve a failing baseline, state a prediction, alter one variable, and compare the same evidence before combining fixes.

1	Debugging by accumulation produces a passing state without showing which change mattered. That makes rollback risky and leaves the underlying model of the failure unverified.
2
3	- Capture the failing command, inputs, environment, code revision, seed, time window, and observable result before editing code or data.
4	- State the hypothesis and its predicted evidence in advance, including what result would disprove it.
5	- Change one code path, configuration value, dependency, data property, timing condition, or resource limit while holding the rest constant.
6	- Repeat the same reproduction and compare structured evidence; revert ineffective probes so they do not contaminate the eventual fix.
7
8	See /tests for the adjacent decision or procedure that completes this constraint.

Memories

A symptom timeline narrows the causal search/docs/debuggingOrder user action, request, state changes, dependency calls, logs, and failure by stable identifiers and clocks.

1	The first error message is often downstream of the initiating event. A timeline built from correlated evidence reveals which state changed first and which failures are consequences.
2
3	- Start from the user-visible or externally observed failure and trace backward through request, job, event, and data identities.
4	- Normalize timestamps and note clock uncertainty across machines; ordering by wall clock alone can invert distributed events.
5	- Separate facts from interpretation and annotate missing evidence instead of filling gaps with a plausible narrative.
6	- Compare a successful and failing timeline to find the earliest meaningful divergence rather than the largest later error.
7
8	See /src for the rule or workflow that puts this decision into practice.

Root cause explains mechanism and necessary conditions/docs/debuggingA cause account names the defect, trigger, state transition, and missing defense, not merely the component that threw.

1	A useful root cause predicts when the bug will and will not happen. Naming a null value, timeout, race, or bad deployment without the mechanism does not guide a durable fix.
2
3	- Describe the incorrect assumption or invariant violation and the exact path that allowed it to become observable.
4	- List the triggering input, timing, load, version, or state conditions and distinguish necessary from incidental conditions.
5	- Identify why existing types, validation, tests, monitoring, rollout, or recovery controls did not prevent or reveal the defect earlier.
6	- Verify the explanation by reproducing the failure with the cause present and eliminating it with the targeted fix while keeping other conditions stable.
7
8	See /tests for the rule or workflow that puts this decision into practice.

Skills

triage-software-defect/rootStabilize a debugging session by capturing scope, evidence, reproduction, recent change, and ranked hypotheses.

1	---
2	name: triage-software-defect
3	description: Triage a newly reported software defect before broad code changes begin.
4	---
5
6	# Triage Software Defect
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	- [ ] Write one observable failure statement with expected behavior, actual behavior, affected users or data, frequency, and first known occurrence.
11	- [ ] Capture logs, traces, screenshots, payload identity, database state, environment, versions, and exact commands without collecting unnecessary secrets or personal data.
12	- [ ] Find the smallest reliable reproduction or a production evidence query when local reproduction is unsafe or impossible.
13	- [ ] Compare recent code, configuration, dependency, schema, data, traffic, and infrastructure changes against the failure start time.
14	- [ ] Rank a short hypothesis list by explanatory power and test cost, then choose the first experiment with a falsifiable predicted result.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

prove-root-cause-and-fix/rootDemonstrate the causal mechanism, implement the narrow fix, and add evidence that fails before and passes after.

1	---
2	name: prove-root-cause-and-fix
3	description: Close a debugging investigation only after the root cause and repair are causally verified.
4	---
5
6	# Prove Root Cause And Fix
7
8	Run this procedure when the affected surface changes, before the result is promoted to production. Record evidence for every step instead of accepting a plausible-looking result.
9
10	1. Construct the minimal failing case and record the state transition or interleaving that violates the intended invariant.
11	2. Run the case on the prior code and confirm the predicted failure using deterministic or statistically sufficient repetition.
12	3. Apply the narrowest repair at the ownership boundary and rerun the identical case without weakening assertions or hiding the symptom.
13	4. Add a regression test, invariant check, or observability signal that would fail on the old mechanism and remain stable under normal variation.
14	5. Document cause, trigger, scope, fix, verification, rollout risk, rollback, and deliberately excluded adjacent problems.
15
16	## Exit criteria
17
18	The change is complete only when the expected behavior, failure behavior, and rollback path have all been exercised with representative data. Preserve the evidence with the change so the next operator can repeat the same checks.

Why this pattern

AI agents often patch the line named by a stack trace, change multiple variables, or declare a race fixed because it did not reproduce once.

Built for Engineering teams diagnosing deterministic, intermittent, data-dependent, distributed, or performance defects.

Keeps your assistant from:

Destroying the failing state before capturing evidence
Confusing the first visible symptom with the initiating cause
Accepting a non-reproduction as proof of repair
Shipping a fix without a regression test or causal explanation

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25