86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# Fault Locate — Step-by-Step Guide
|
||
|
||
## Step 1: Understand the Failure
|
||
|
||
Characterize it precisely:
|
||
- **Observed behavior:** exact error message, wrong output value, or symptom
|
||
- **Expected behavior:** from the test assertion, documentation, or user description
|
||
- **Reproduction path:** which inputs, environment, sequence of operations
|
||
|
||
If a stack trace is available, note the innermost frame (actual crash point) separately from the function that caused it (which may be higher in the stack).
|
||
|
||
## Step 2: Identify the Entry Point
|
||
|
||
Start from the closest code entry point to the failure:
|
||
- Failing test → the test function
|
||
- Stack trace → the outermost **application** frame (not a library frame)
|
||
- Described symptom ("API returns 500") → the request handler
|
||
|
||
Do not start from `main()` — start from the function closest to the failure.
|
||
|
||
Start inside the **failure cone**:
|
||
- Stack trace frames from application code
|
||
- The failing test and fixtures directly setting up the failing state
|
||
- Local callees reached by the failing path
|
||
- Config/env values read by those frames
|
||
|
||
Do not inspect unrelated modules, alternative endpoints, or neighboring tests unless the backward trace reaches them.
|
||
|
||
## Step 3: Trace Backward from the Failure Point
|
||
|
||
Working from the failure site, trace backward: "Where did this value/state come from?"
|
||
|
||
At each step:
|
||
- Follow the value to its origin: declaration, assignment, callee return, external state
|
||
- Build premises: what was assumed about this value? What is its actual value?
|
||
|
||
**Minimum thresholds** (per `../_shared/semiformal-guide.md`): ≥ 3 substantive hops and ≥ 2 location anchors. Otherwise downgrade Fault Confidence to Low.
|
||
|
||
**Good backward trace:**
|
||
```
|
||
Symptom: TypeError at service.py:7 — 'NoneType' object is not subscriptable on `result['transaction_id']`.
|
||
←1. [service.py:7] `result` came from line 6.
|
||
←2. [service.py:6] `result = charge(order)`; `charge` resolves to `payments.gateway.charge`.
|
||
←3. [gateway.py:3-4] `charge` returns None when `order.amount == 0`; all other paths return a dict.
|
||
←4. Failing test passes an order with `amount == 0`.
|
||
Root: gateway.py returns None on amount==0; service.py assumes dict unconditionally — L6.
|
||
```
|
||
|
||
## Step 4: Trace Forward to Confirm
|
||
|
||
From the suspected fault location, trace forward:
|
||
- Does execution reach the failure site?
|
||
- Does the fault produce exactly the observed symptom?
|
||
|
||
If yes, the hypothesis is confirmed. If not, revise — the actual fault may be earlier or in a different branch.
|
||
|
||
## Step 5: Interprocedural Tracing
|
||
|
||
If the backward trace implicates a callee, trace into it:
|
||
- Does the callee return `None` under the observed conditions?
|
||
- Does the callee raise an exception the caller doesn't handle?
|
||
- Does the callee mutate shared state affecting the caller's subsequent behavior?
|
||
|
||
The fault is often not in the function being looked at — it is in a callee that doesn't behave as assumed (L6), or in a name that resolves differently (L1).
|
||
|
||
Depth budget: follow the concrete failing path first and stop after the root cause is confirmed. If more than four local calls are required, state the remaining call-chain assumption and downgrade Fault Confidence unless a test or stack trace directly confirms the deeper hop.
|
||
|
||
## Step 6: Identify the Root Divergence
|
||
|
||
State precisely:
|
||
- The specific line/expression where the divergence **originates** (not the crash site — the cause of the crash)
|
||
- The premise that was violated
|
||
- The actual value or behavior
|
||
- Why this propagated to the observed failure
|
||
|
||
Contributing Factors: conditions that enabled the fault (not findings themselves, but context for the fix).
|
||
|
||
## Step 7: Classify and Output
|
||
|
||
1. Assign the L-code (L1–L9) that best describes the root fault.
|
||
2. Assess Fault Confidence:
|
||
- **High:** trace fully confirms — Premises→Trace→Divergence form a complete chain from cause to symptom.
|
||
- **Medium:** trace strongly implicates, but one step rests on an unverified assumption.
|
||
- **Low:** plausible fault, but alternative causes cannot be ruled out without execution.
|
||
3. Output: Primary Fault (five-field finding for root cause) + Contributing Factors + Remedy.
|