# Pathrule Pattern: Debugging and Root Cause Analysis (1.0.0) # ::pathrule:package:debugging-root-cause ### [RULE] Change one causal variable at a time (path: /src) 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. - Capture the failing command, inputs, environment, code revision, seed, time window, and observable result before editing code or data. - State the hypothesis and its predicted evidence in advance, including what result would disprove it. - Change one code path, configuration value, dependency, data property, timing condition, or resource limit while holding the rest constant. - Repeat the same reproduction and compare structured evidence; revert ineffective probes so they do not contaminate the eventual fix. See /tests for the adjacent decision or procedure that completes this constraint. --- ### [MEMORY] A symptom timeline narrows the causal search (path: /docs/debugging) 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. - Start from the user-visible or externally observed failure and trace backward through request, job, event, and data identities. - Normalize timestamps and note clock uncertainty across machines; ordering by wall clock alone can invert distributed events. - Separate facts from interpretation and annotate missing evidence instead of filling gaps with a plausible narrative. - Compare a successful and failing timeline to find the earliest meaningful divergence rather than the largest later error. See /src for the rule or workflow that puts this decision into practice. --- ### [MEMORY] Root cause explains mechanism and necessary conditions (path: /docs/debugging) 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. - Describe the incorrect assumption or invariant violation and the exact path that allowed it to become observable. - List the triggering input, timing, load, version, or state conditions and distinguish necessary from incidental conditions. - Identify why existing types, validation, tests, monitoring, rollout, or recovery controls did not prevent or reveal the defect earlier. - Verify the explanation by reproducing the failure with the cause present and eliminating it with the targeted fix while keeping other conditions stable. See /tests for the rule or workflow that puts this decision into practice. --- ### [SKILL] triage-software-defect (path: /) --- name: triage-software-defect description: Triage a newly reported software defect before broad code changes begin. --- # Triage Software Defect 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. - [ ] Write one observable failure statement with expected behavior, actual behavior, affected users or data, frequency, and first known occurrence. - [ ] Capture logs, traces, screenshots, payload identity, database state, environment, versions, and exact commands without collecting unnecessary secrets or personal data. - [ ] Find the smallest reliable reproduction or a production evidence query when local reproduction is unsafe or impossible. - [ ] Compare recent code, configuration, dependency, schema, data, traffic, and infrastructure changes against the failure start time. - [ ] Rank a short hypothesis list by explanatory power and test cost, then choose the first experiment with a falsifiable predicted result. ## Exit criteria 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. --- ### [SKILL] prove-root-cause-and-fix (path: /) --- name: prove-root-cause-and-fix description: Close a debugging investigation only after the root cause and repair are causally verified. --- # Prove Root Cause And Fix 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. 1. Construct the minimal failing case and record the state transition or interleaving that violates the intended invariant. 2. Run the case on the prior code and confirm the predicted failure using deterministic or statistically sufficient repetition. 3. Apply the narrowest repair at the ownership boundary and rerun the identical case without weakening assertions or hiding the symptom. 4. Add a regression test, invariant check, or observability signal that would fail on the old mechanism and remain stable under normal variation. 5. Document cause, trigger, scope, fix, verification, rollout risk, rollback, and deliberately excluded adjacent problems. ## Exit criteria 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.