diagnose-failure · diff
git:20260827.1fe06cc to git:20260908.9097a1e
64 added, 196 removed. Audit A to A.
---
name: diagnose-failure
- description: Use when a bug, failure, regression, performance problem, or repeated unsuccessful correction lacks a supported cause.
+ description: "Use when a bug, failure, regression, performance problem, or repeated unsuccessful correction lacks a supported cause."
---
# Diagnose Failure
- Establish what is failing and why before selecting a correction.
-
- A **diagnostic loop** is a repeatable observation that can support, contradict, or leave unresolved a hypothesis at the boundary where the failure matters.
-
- A **supported cause** is a causal explanation strong enough to distinguish meaningful alternatives and bound the next action. It does not require impossible certainty.
-
- A requested patch, plausible code path, reviewer theory, observation consistent with one hypothesis, or one favorable rerun is not a supported cause.
-
- Diagnosis owns the hypothesis, causal interpretation, and correction boundary. It does not authorize active evidence generation or correction.
-
- ## Enter Only When Cause Is Unsettled
+ Establish what fails and why before selecting a correction. A supported cause distinguishes meaningful alternatives well enough to bound the next action; it does not require impossible certainty.
- Use diagnosis for:
+ A plausible path, requested patch, reviewer theory, or favorable rerun is not a supported cause. Diagnosis owns the causal question, interpretation, and correction boundary—not authority to run experiments or change production.
- - an unexplained bug, failed test, regression, or runtime failure;
- - flaky, timing-dependent, environmental, or performance behavior;
- - contradictory evidence;
- - related corrections that keep failing;
- - patches that repeatedly expose additional state or coordination;
- - review findings whose shared cause remains unsupported.
+ ## Enter For An Unsettled Cause
- Do not diagnose an ordinary mistake when fresh evidence already establishes one clear local defect and accepted behavior is settled. Return that correction to [Workflow](../../skills/workflow/SKILL.md).
+ Use diagnosis for unexplained bugs, failed checks, regressions, flaky or environmental behavior, contradictory observations, and corrections that repeatedly fail or expose related coordination.
- Review count, finding count, or several bugs in one area do not by themselves prove a shared or structural cause.
+ Do not investigate an ordinary mistake when fresh evidence already establishes a clear local defect and the accepted remedy. Return that correction to [Workflow](../../skills/workflow/SKILL.md). Finding count or several bugs in one area does not establish a shared structural cause.
- Diagnosis may recur inside one Slice. A new hypothesis or observation does not create a new Slice by itself. When a Working Record exists, use [Track Work](../../skills/track-work/SKILL.md) to preserve the current hypothesis, evidence, blocker, and next distinguishing action.
+ Keep diagnosis within the same coherent Slice. Use [Track Work](../../skills/track-work/SKILL.md) when continuity requires preserving the hypothesis, discriminating evidence, rejected approaches, blocker, and next useful action. Do not record every trial.
- ## Establish The Failure Boundary
+ ## Establish The Failure, Not The Proposed Fix
- Before generating new evidence, identify:
+ Identify only what the investigation needs:
- - the failure claim;
- accepted expected behavior and its source;
- - observed behavior and existing evidence;
- - reported input, state, environment, and reproduction path;
- - the strongest boundary currently observed;
- - differences between the reported path and available reproduction;
- - evidence that already contradicts possible explanations.
-
- Prefer the reported path, environment, and observer. A nearby failure may suggest a hypothesis but does not establish the reported failure.
+ - observed symptom and available counterevidence;
+ - relevant input, state, environment, timing, and reported path;
+ - the strongest boundary actually observed;
+ - any difference between that boundary and the reported failure.
- Reduced-fidelity reproduction remains diagnostic evidence only. State what it cannot prove.
+ Prefer the reported path and environment. A nearby symptom may suggest a hypothesis but does not reproduce the reported defect. State reduced-fidelity limits explicitly.
- Allowed behavior is not reproduction. A cache hit does not prove a stale-read defect when caching is permitted. A possible race in source does not explain a report until timing, traces, state, or accepted behavior connects it.
+ Allowed behavior is not a bug: a cache hit does not establish stale-read failure when caching is permitted. A possible race in source is not the cause without evidence connecting its timing and state to the symptom.
- ## State Competing Hypotheses
+ Use [Decision Gate](../../skills/decision-gate/SKILL.md) when accepted behavior or source truth is unsettled. Do not invent an expectation and then diagnose why the implementation violates it.
- State one falsifiable leading hypothesis and only the viable alternatives the next observation must distinguish.
+ ## Choose A Distinguishing Observation
- For each, identify:
+ State a falsifiable leading explanation and only the viable alternatives the next observation must distinguish:
```text
Hypothesis:
Predicted observation:
- Observation that would contradict it:
+ What would contradict it:
Meaningful alternative:
```
- Do not create a hypothesis around the requested patch and then use that hypothesis to prove the patch is necessary.
-
- When accepted behavior, source truth, or a user-owned choice is unsettled, use [Decision Gate](../../skills/decision-gate/SKILL.md) rather than diagnosing an invented expectation.
-
- ## Choose One Distinguishing Loop
-
- Choose the smallest observation whose possible outcomes differ between the meaningful hypotheses at the required boundary.
-
- When the exact loop is not obvious, or several loop shapes remain plausible, read the [Diagnostic Loop Catalog](references/diagnostic-loop-catalog.md).
-
- When timing, randomness, environmental variance, concurrency, or resource behavior shapes the failure, also read [Flaky and Performance Diagnosis](references/flaky-and-performance-diagnosis.md) before selecting or running the loop.
-
- When several tools or observers could execute the same selected loop, or the likely interaction is broad, use [Action Selection](../../skills/action-selection/SKILL.md). It selects the interaction; Diagnose Failure retains the hypothesis and causal question.
-
- Before an active observation, confirm that the authority envelope covers:
-
- - the exact path and environment;
- - mutation, repetition, instrumentation, and cost;
- - evidence collection and sensitive-data handling;
- - cleanup, rollback, or recovery.
-
- Otherwise return the loop's purpose, expected distinguishing evidence, and stop condition to Workflow and wait.
-
- When no safe useful loop exists, stop with the smallest missing evidence: failing input, command, trace, log window, seed, timestamp, environment, permission, or isolated instrumentation.
-
- ## Run And Interpret One Iteration
-
- Run one covered observation and change one distinguishing variable at a time.
-
- Apply [Verify Work](../../skills/verify-work/SKILL.md) when the observation requires its full claim-and-boundary method. Diagnosis retains ownership of causal inference after verification returns the evidence.
-
- Keep three results separate.
-
- ### Check Result
-
- How did the selected observation's defined assertion execute?
-
- Use Verify Work's check-result semantics:
-
- - **Passed:** the observation executed validly and its assertion held.
- - **Failed:** the observation executed validly and its assertion did not hold.
- - **Error:** the observer or execution was invalid.
- - **Unavailable:** the observation could not be attempted safely or reliably.
-
- A target path may intentionally fail while the diagnostic check Passes. An Error or Unavailable observer says nothing about the production cause.
-
- ### Hypothesis Result
-
- What does the evidence establish about the tested hypothesis?
-
- - **Supported:** direct evidence establishes the hypothesis at its stated boundary.
- - **Contradicted:** evidence shows the hypothesis is false.
- - **Inconclusive:** the observation cannot distinguish it from meaningful alternatives.
- - **Unavailable:** the required evidence cannot currently be obtained.
+ Choose a repeatable diagnostic loop whose possible results differ between those explanations. Do not build a hypothesis around the requested patch and then treat consistency with it as proof of necessity.
- ### Cause Status
+ Read [Diagnostic Loop Catalog](references/diagnostic-loop-catalog.md) when the exact loop is not obvious or several loop shapes are plausible. Read [Flaky and Performance Diagnosis](references/flaky-and-performance-diagnosis.md) when timing, randomness, environment, concurrency, or resources shape the failure.
- - **Supported:** the evidence establishes a useful causal explanation.
- - **Unresolved:** one or more causal links or meaningful alternatives remain open.
+ Use [Action Selection](../../skills/action-selection/SKILL.md) when tools, targets, or observers for the selected causal question remain uncertain or broad. Stop reading when adequate context supports the experiment; the objective is not exhaustive understanding of the subsystem.
- A Supported hypothesis does not automatically establish a Supported cause.
+ Before active evidence generation, confirm that the agreement covers the path, environment, repetition, instrumentation, cost, sensitive-data handling, and cleanup or recovery. Covered bug investigation needs no extra permission solely because it is diagnosis. Otherwise return the proposed observation and stop condition to Workflow and wait.
- A cause is Supported only when the evidence:
+ If no safe useful observer is available, report the smallest missing input, trace, environment, permission, or instrumentation rather than patching a guess.
- 1. establishes the relevant failure or strongest available observer;
- 2. behaves as the causal explanation predicts;
- 3. materially weakens meaningful alternatives;
- 4. connects trigger and state through mechanism to the observed symptom;
- 5. is sufficient to bound a correction or other next action without guessing.
+ ## Interpret One Iteration
- If evidence supports only the strongest remaining hypothesis, report it as such and identify the observation that would confirm or refute the missing causal link.
+ Run one covered observation, changing one distinguishing variable at a time. Use [Verify Work](../../skills/verify-work/SKILL.md) for its claim-and-boundary method when needed. Diagnosis retains ownership of causal inference.
- ## Route From The Iteration
+ Keep three results separate:
- - **Check Error:** repair or replace the observer; do not change production code.
- - **Check Unavailable:** stop with the missing evidence or authority.
- - **Hypothesis Contradicted:** preserve the evidence, then refine or replace the hypothesis.
- - **Hypothesis Inconclusive:** choose a sharper distinguishing loop.
- - **Hypothesis Supported, cause Unresolved:** test the remaining causal link or alternative.
- - **Cause Supported:** return the causal explanation and correction boundary to Workflow.
- - **Behavior or source conflict:** use Decision Gate.
- - **Supported structural pressure:** apply [Design for Depth](../../skills/design-for-depth/SKILL.md) under the current owner.
- - **Active harm before cause:** return one bounded containment option to Workflow.
+ - **Check result:** Passed, Failed, Error, or Unavailable under Verify Work's assertion-relative meanings. Observing an expected target failure can be a Passed check.
+ - **Hypothesis result:** Supported, Contradicted, Inconclusive, or Unavailable at the stated observing boundary.
+ - **Cause status:** Supported or Unresolved.
- Do not continue because diagnosis started. Stop when no safe observation can materially improve the route.
+ A supported hypothesis need not establish the cause. A useful supported cause connects trigger and state through mechanism to the symptom, predicts the observations, materially weakens viable alternatives, and is sufficient to bound a correction without guessing.
- ## Protect Diagnostic Evidence
+ If only the strongest remaining hypothesis is supported, say so and identify its missing causal link. Do not claim certainty from one consistent observation.
- Treat logs, traces, payloads, screenshots, dumps, production samples, and browser state as potentially sensitive. Minimize and sanitize them. Do not expose credentials, tokens, unrestricted personal data, or private payloads.
+ Route from the result:
- Bound repetition by time, cost, side effects, and environment safety. Do not repeatedly exercise mutating production behavior without explicit authority and an understood recovery boundary.
+ - Check Error -> repair or replace the observer, not production.
+ - Check Unavailable -> return the missing evidence or authority.
+ - Hypothesis Contradicted -> preserve the result and revise the explanation.
+ - Hypothesis Inconclusive -> choose a sharper observer if one is useful and covered.
+ - Hypothesis Supported, cause Unresolved -> test the remaining material link or alternative.
+ - Cause Supported -> return the correction boundary.
- Temporary instrumentation must distinguish hypotheses. Keep it isolated and state:
+ Stop when the cause is sufficiently supported or no covered observation can materially improve the decision. Do not keep investigating merely because stronger certainty is imaginable.
- - what it observes;
- - mutation or performance impact;
- - cleanup and removal condition;
- - whether it remains after diagnosis.
+ ## Keep The Investigation Inside The Task
- Preserve contradictory and unfavorable evidence. Do not rerun until it disappears.
+ Before following another prerequisite, distinguish a limitation of the current observer or approach from a requirement of the accepted outcome. A failed reproduction method is not proof that production needs new infrastructure, stronger guarantees, or a host change.
- ## Identify The Owning Cause
+ Choose the smallest supported correction preserving accepted behavior. If the remedy changes scope, compatibility, public behavior, failure semantics, or another user-owned boundary, return the concrete consequence and alternatives through Workflow before adopting it.
- Classify only what evidence supports:
+ Classify only the owning cause supported by evidence:
- local implementation defect;
- invalid, stale, or inadequate check;
- - environment, dependency, data, timing, or configuration cause;
- - missing observer or insufficient evidence;
+ - environment, dependency, data, timing, or configuration issue;
+ - missing observer or evidence;
- unsettled behavior or source conflict;
- - wrong result, scope, order, or execution strategy;
+ - wrong result, scope, order, or strategy;
- structural ownership, interface, state, or failure-unit pressure.
- Diagnosis determines whether observed pressure is causal.
-
- Use Design for Depth only after diagnosis establishes structural pressure, or when direct design evidence independently establishes caller coordination, distributed policy, unowned state, interface leakage, or failure-unit pressure. Design for Depth shapes the supported ownership boundary; it does not re-prove the cause.
-
- If design work exposes an unsupported causal assumption that changes the boundary choice, re-enter diagnosis with that exact assumption and the alternatives it must distinguish.
-
- ## Contain Harm Without Claiming A Fix
-
- When immediate harm must be limited before cause is Supported, return one bounded containment option to Workflow.
-
- Containment must:
-
- - reduce immediate harm;
- - remain narrower and more reversible than a guessed correction;
- - preserve diagnostic evidence;
- - define verification and recovery;
- - avoid settling unresolved behavior;
- - be reported as mitigation, not resolution.
-
- A requested patch may instead be an authorized learning action. Its result can strengthen or weaken a hypothesis; it does not become selected production behavior automatically.
-
- ## Return The Correction Boundary
-
- When cause is Supported, return:
-
- - failure claim and required boundary;
- - diagnostic loop and observation;
- - check result and hypothesis result;
- - causal chain;
- - alternatives weakened and uncertainty remaining;
- - owning cause;
- - smallest coherent correction boundary;
- - minimized regression signal;
- - original reported path or strongest available observer.
-
- The evidence supports the route but does not authorize correction.
+ Use [Design for Depth](../../skills/design-for-depth/SKILL.md) when causal or direct design evidence establishes structural pressure. It shapes the boundary without re-proving the cause. If design reveals an unsupported causal premise, return to diagnosis with that exact uncertainty.
- Return an authorized correction to [Execute Work](../../skills/execute-work/SKILL.md). Use [TDD](../../skills/tdd/SKILL.md) when the diagnostic loop supplies a stable failing behavior check. Use [Simplify Code](../../skills/simplify-code/SKILL.md) only when the supported cause shows that obsolete or workaround machinery can be removed without changing accepted behavior. Do not use cleanup in place of correcting the supported failure or while its evidence remains unresolved.
+ ## Protect Evidence And Contain Harm
- After correction, use Verify Work to check both:
+ Logs, traces, payloads, dumps, screenshots, and browser state may be sensitive. Minimize and sanitize them; do not expose credentials or unnecessary private data. Bound repetitions by time, cost, effects, and environment safety. Preserve unfavorable evidence rather than rerunning until it disappears.
- 1. the minimized regression signal;
- 2. the original reported path or strongest available observer.
+ Temporary instrumentation must distinguish hypotheses. Keep it isolated and state its observer, mutation/performance impact, removal condition, and whether it remains afterward.
- If correction fails, or exposes related shared-state consequences, re-enter diagnosis before another patch.
+ When immediate harm needs containment before diagnosis is settled, return one narrower, reversible mitigation to Workflow. It must preserve evidence, define checking and recovery, and avoid settling undefined behavior. Report mitigation as containment, not resolution.
- Do not claim fixed when only containment succeeded, a nearby check passed, or the original boundary remains unavailable.
+ A requested experimental patch can generate evidence when authorized as learning. It does not automatically select production behavior or authorize continuing beyond its question.
- ## Report Proportionately
+ ## Return A Supported Correction Boundary
- For one unresolved iteration:
+ Return proportionately:
- ```text
- Failure @ boundary:
- Diagnostic loop:
- Check result:
- Hypothesis result:
- Cause status: Unresolved
- Next distinguishing evidence:
- ```
+ - failure and accepted expectation at the required boundary;
+ - observed diagnostic loop, check result, and hypothesis result;
+ - causal chain, alternatives weakened, and remaining uncertainty;
+ - owning cause and smallest coherent correction;
+ - minimized regression signal and original reported path or strongest available observer;
+ - instrumentation, containment, residual effects, and authority limits.
- For a supported cause, containment, conflicting evidence, or a route handoff:
+ An already-covered correction can return to [Execute Work](../../skills/execute-work/SKILL.md). Preserve the diagnostic evidence and use suitable regression checks without prescribing a formal test-first sequence. Use [Verify Work](../../skills/verify-work/SKILL.md) to design or classify those checks. Use [Simplify Code](../../skills/simplify-code/SKILL.md) only for an accepted behavior-preserving removal of obsolete or workaround machinery, not as a substitute for the fix.
- ```text
- Failure claim:
- Required boundary:
- Expected / observed:
- Diagnostic loop and evidence:
- Check result:
- Hypothesis result:
- Cause status:
- Causal explanation or strongest remaining hypothesis:
- Alternatives weakened / unresolved:
- Containment or instrumentation:
- Correction boundary or next evidence:
- Post-correction verification:
- ```
+ After correction, verify the minimized regression signal and the original reported path or strongest available observer. A nearby passing test is insufficient. If the fix fails or reveals related shared-state consequences, re-enter the affected causal question before another patch.
- Omit fields that do not apply. Stop when the supported route, missing evidence, containment boundary, or unresolved decision is explicit.
+ Stop with the supported correction, missing evidence, containment boundary, or unresolved decision explicit. Do not claim fixed when only mitigation succeeded or the reported boundary remains unverified.