jungho-git/failure

Failure

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Scope

Use this rule when:

• runtime errors occur
• tests, builds, scripts, jobs, routes, or workflows fail
• a regression is reported without a confirmed cause
• logs show downstream noise and the first break point is unclear
• a fix is tempting but not yet justified by evidence

Failure analysis should turn a symptom into an evidence-backed cause before implementation.

---

Isolation Order

• Establish the smallest reliable reproduction path.
• Capture the first visible symptom exactly: command, input, expected behavior, actual behavior, and first useful error.
• Trace the shortest execution path from entry point to failure.
• Separate upstream cause from downstream stack traces, retries, wrappers, and error handlers.
• Form a short hypothesis list tied to concrete files, contracts, data, config, or environment.
• Test hypotheses one at a time.
• Patch only after the first break point is confirmed or the remaining assumption is explicit and narrow.

Do not start from architecture guesses when the failing path is observable.

---

Evidence To Capture

• reproduction command or manual path
• environment or data precondition needed to reproduce
• first symptom and first useful failure output
• expected contract and actual contract
• entry point, caller chain, and dependency edge involved
• data, schema, config, permission, timezone, encoding, concurrency, or transaction condition when relevant
• confirmed break point or strongest remaining hypothesis
• uncertainty that still blocks a safe patch

Keep evidence short and source-bound.

---

Hypothesis Rules

• Prefer two or three plausible hypotheses over a broad possibility list.
• Tie each hypothesis to a specific check that can confirm or falsify it.
• Drop hypotheses that no longer fit observed evidence.
• Treat flaky, timing, concurrency, and environment failures as reproducible through conditions, not as unknowable.
• When local reproduction is impossible, use logs, traces, fixtures, schema, config, and source inspection to narrow the cause before editing.

Each hypothesis should move toward a decision.

---

Patch Readiness Gate

Patch only when at least one condition is true:

• the break point is confirmed by reproduction, test, log, trace, or direct source evidence
• the failing contract is identified and the required behavior is clear
• local reproduction is blocked, but the evidence leaves one narrow, stated assumption

Do not patch when evidence only says a downstream component complained.

---

Verification

• Re-run the original failing path after the fix when execution is available.
• Add or run the narrowest regression check that proves the break point stays fixed.
• Validate adjacent behavior only when the patch touches shared contracts, data, config, schemas, or concurrency.
• Report not run or could not run instead of implying verification.

Verification should prove the original failure path, not only syntax.

---

Output Shape

• reproduction
• first symptom
• confirmed or likely break point
• evidence
• patch readiness
• verification path
• remaining uncertainty

Use this shape for failure notes, handoffs, and pre-patch summaries.

---

Boundaries

• Do not patch before the cause is confirmed or a narrow assumption is stated.
• Do not confuse a downstream stack trace with the origin.
• Do not skip reproduction when it can be established locally.
• Do not create mock-only proxies instead of inspecting the real failing file or path.
• Do not broaden a fix into unrelated cleanup while isolating a failure.