Systematic Diagnosis
Determine the most strongly supported cause before changing the system.
Read intermittent failure diagnosis for flaky tests, order-dependent failures, timing, or suspected races.
Workflow
- Capture the observed symptom, expected behavior, environment, and smallest known reproduction.
- Reproduce safely when possible. Preserve the exact command, input, output, and revision.
- Map the path from input to failure and identify the first boundary where observed state diverges from expected state.
- Form a small set of competing hypotheses with discriminating tests.
- Run the cheapest read-only or reversible test that can eliminate a hypothesis.
- Check whether the failure is isolated, environment-specific, order-dependent, intermittent, or shared by related paths.
- Stop when one cause is supported well enough to explain the evidence, or report the remaining uncertainty explicitly.
Boundaries
- Diagnosis does not authorize implementation. Do not edit files, restart shared services, change remote state, or deploy unless the user also requested a fix.
- Do not label correlation, a passing standalone test, or the last changed file as the cause without a causal check.
- Treat sandbox, permission, network, and provider failures as environment evidence until product behavior is independently implicated.
Output
Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.
Report Symptom, Reproduction, Cause, Evidence, Alternatives eliminated, Impact, and Fix direction. If no cause is established, say Diagnosis incomplete and name the next discriminating observation.
Example
Synthetic example; not an observed client result.
Input: The build started failing after a dependency update, but the failing command, lockfile diff, and error output are missing.
Output: Diagnosis incomplete. The reported symptom is a build failure after the update; reproduction and cause are unverified. No competing cause has been eliminated, and the affected build is blocked. Next observation: obtain the exact command and error, then compare the same command and environment with the prior lockfile. No rollback or source change has been made.
1---2name: diagnose-failure3description: "Diagnoses failures when asked \"why is the build failing\", \"why did this regress\", or \"what caused this error\"; reproduces and tests hypotheses before proposing a fix. Loads before file inspection when the request matches."4license: MIT5metadata:6 source: https://skillmd.com/skills/jovanipink/diagnose-failure7 author: "Measured Studios"8 version: "0.19.0"9 plugin: "measured-workflows"10 invocation: "implicit"11 provenance: "original"12 risk_class: "bounded-execution"13---1415# Systematic Diagnosis1617Determine the most strongly supported cause before changing the system.1819Read [intermittent failure diagnosis](references/nondeterministic-failures.md) for flaky tests, order-dependent failures, timing, or suspected races.2021## Workflow22231. Capture the observed symptom, expected behavior, environment, and smallest known reproduction.242. Reproduce safely when possible. Preserve the exact command, input, output, and revision.253. Map the path from input to failure and identify the first boundary where observed state diverges from expected state.264. Form a small set of competing hypotheses with discriminating tests.275. Run the cheapest read-only or reversible test that can eliminate a hypothesis.286. Check whether the failure is isolated, environment-specific, order-dependent, intermittent, or shared by related paths.297. Stop when one cause is supported well enough to explain the evidence, or report the remaining uncertainty explicitly.3031## Boundaries3233- Diagnosis does not authorize implementation. Do not edit files, restart shared services, change remote state, or deploy unless the user also requested a fix.34- Do not label correlation, a passing standalone test, or the last changed file as the cause without a causal check.35- Treat sandbox, permission, network, and provider failures as environment evidence until product behavior is independently implicated.3637## Output3839Lead with the answer. Use the shortest format that retains the required evidence and limits; expand when requested or needed. The items below describe required content, not mandatory headings.4041Report `Symptom`, `Reproduction`, `Cause`, `Evidence`, `Alternatives eliminated`, `Impact`, and `Fix direction`. If no cause is established, say `Diagnosis incomplete` and name the next discriminating observation.4243## Example4445Synthetic example; not an observed client result.4647Input: The build started failing after a dependency update, but the failing command, lockfile diff, and error output are missing.4849Output: Diagnosis incomplete. The reported symptom is a build failure after the update; reproduction and cause are unverified. No competing cause has been eliminated, and the affected build is blocked. Next observation: obtain the exact command and error, then compare the same command and environment with the prior lockfile. No rollback or source change has been made.