scientific-fault-isolation
Skill4 starsChanged 31 days agoMITView on GitHub
Enforces Microsoft and Meta surgical debugging discipline to eliminate shotgun debugging, speculative code edits, and non-deterministic bug masking. Use when investigating mysterious production crashes, intermittent race conditions, flaky tests, Heisenbugs, silent data corruption, or regressions with unknown root causes — even if the user doesn't explicitly say "scientific fault isolation". Do NOT use for deterministic syntax/compile errors with obvious stack traces, greenfield feature implementation, or purely architectural layer-ownership decisions already isolated by root-fix-gate.
In this repository47 other files it gives its agents.
- AGENTS.mdAGENTS.md
- anti-slop-engineeringSkill
- anti-slop-engineeringSkill
- api-ergonomics-and-contract-governorSkill
- apple-craft-and-frame-budgetSkill
- apple-craft-and-interaction-physicsSkill
- asset-provenance-guardSkill
- backprop-guardSkill
- chaos-and-degradation-choreographerSkill
- chromatic-drift-guardSkill
- cognitive-load-and-attention-governorSkill
- comment-budget-guardSkill
- context-window-and-token-economics-architectSkill
- cryptographic-agility-and-secret-lifecycle-gateSkill
- decision-guardSkill
- demock-guardSkill
- design-system-drift-guardSkill
- deterministic-simulation-and-property-testingSkill
- distributed-consensus-and-concurrency-gateSkill
- finops-and-unit-economics-governorSkill
- future-scale-gateSkill
- grumpy-senior-staff-engineerSkill
- honeypot-trap-guardSkill
- house-tell-guardSkill
- install-anti-slopSkill
- llm-eval-and-prompt-injection-fortressSkill
- mandela-guardSkill
- mechanical-sympathy-and-perf-gateSkill
- mechanical-sympathy-profilerSkill
- motion-runtime-guardSkill
- observability-and-slo-architectSkill
- observability-and-slo-gateSkill
- paranoid-principal-architectSkill
- pr-boundary-guardSkill
- privacy-and-data-lineage-gateSkill
- re0-handoff-guardSkill
- reduction-guardSkill
- repo-memory-and-invariant-stewardSkill
- root-fix-gateSkill
- safe-evolution-and-rollout-choreographerSkill
- styleseed-guardSkill
- supply-chain-and-sbom-sentinelSkill
- tagore-guardSkill
- type-level-and-ast-slop-gateSkill
- ui-and-copy-disciplineSkill
- verification-oracle-architectSkill
- zero-downtime-migration-gateSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
The Law of $O(\log N)$ Binary Search Isolation: Never trace a 50-step pipeline or 200-commit history linearly from start to finish.
- Very specific: line 40
Temporal Bisection: Use git bisect run <reproducer_cmd> to isolate regressions across commits in $\lceil \log_2(N) \rceil$ steps.
- Distinctive: line 74
Before touching any production file to fix a non-trivial bug, answer these five questions with empirical evidence:
- Distinctive: line 80
Reversibility & Falsification Check: If we revert your proposed 3-line fix while keeping the new regression test, does the test …
- Distinctive: line 105
When a durable fault-isolation record is warranted, save a JSON assessment following the Fault Isolation Record Contract and audit it with:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Scientific Fault Isolation (Microsoft / Meta Surgical Debugging Discipline)
Never mutate production code to test a guess. Formulate 3 falsifiable hypotheses, design one minimal experiment that kills 2 of them with hard evidence, and convert every flaky bug into a 100% deterministic failing test before writing a single line of fix code.
Why This Skill Is Needed & Target State
When faced with an intermittent race condition, a flaky CI test, or an obscure production crash, AI coding agents routinely degenerate into Shotgun Debugging: randomly adding ?. optional chaining, sprinkling await sleep(500) delays, wrapping blocks in try / catch, increasing timeouts, or mutating 5 files in hopes the test turns green. Even when root-fix-gate governs which architectural layer owns a fix, an agent cannot assign ownership if it does not know what physical mechanism caused the fault. Shotgun edits destroy diagnostic evidence, mask concurrency hazards behind timing luck, and stack technical debt on top of unverified assumptions.
The target state is Microsoft and Meta surgical fault isolation: strict adherence to Differential Diagnosis (3 mutually exclusive, falsifiable hypotheses evaluated via a single discriminating probe), Binary Search Isolation ($O(\log N)$ fault space halving across commits via git bisect and across execution boundaries), and Determinism Pinning (freezing wall-clock time, PRNG seeds, and async task interleavings to force intermittent Heisenbugs into 100% reproducible red regression tests before touching production logic).
Activation and Boundaries
| Situation | Behavior |
| Investigating a mysterious bug, crash, or silent data corruption with an unknown mechanism | Freeze production edits; enforce 3-Hypothesis Differential Diagnosis and a discriminating probe |
| Diagnosing an intermittent race condition, deadlock, out-of-order event, or flaky test | Enforce Determinism Pinning (clock, PRNG seed, deterministic scheduler/barrier) to build a 100% red reproducer |
| Tracking down a regression across commit history or a deep multi-service call chain | Execute automated git bisect run or layer-boundary binary search ($O(\log N)$ isolation) |
| Agent has failed 1 fix attempt and is tempted to "try another tweak" | Trigger the Anti-Shotgun Circuit Breaker; revert unverified edits and return to hypothesis falsification |
| Fault mechanism is proven and the question is which architectural boundary owns the invariant | Hand off to root-fix-gate to select the canonical owning layer |
| Obvious compile error, typo, or deterministic stack trace with a known single-line cause | Do not activate; apply standard Anti-Slop Engineering BUILD/FIX gates |
The Five Absolute Laws
- The Anti-Shotgun Law (Zero Speculative Production Edits): Touching a single line of production logic before proving the exact physical fault mechanism is strictly forbidden. You may add read-only diagnostic probes, invariant assertions, or isolated reproduction harnesses, but you must never alter control flow, add defensive null checks, or tweak timeouts to "see if it fixes the problem."
- The Law of Three Falsifiable Hypotheses (Differential Diagnosis): Before running any diagnostic experiment, explicitly write down at least 3 distinct, falsifiable hypotheses ($H_1, H_2, H_3$). Each hypothesis must state a concrete physical mechanism and a specific observable prediction. You must then design the smallest discriminating probe (log point, state snapshot, mock boundary, or minimal reproducer) whose outcome simultaneously falsifies at least 2 of the 3 hypotheses.
- The Law of $O(\log N)$ Binary Search Isolation: Never trace a 50-step pipeline or 200-commit history linearly from start to finish. Always halve the fault space:
- Temporal Bisection: Use
git bisect run <reproducer_cmd>to isolate regressions across commits in $\lceil \log_2(N) \rceil$ steps. - Spatial / Layer Bisection: Inspect the exact midpoint boundary of a data pipeline or call stack (e.g. API gateway payload vs. service input vs. SQL query parameter) to determine which half corrupted the invariant.
- Temporal Bisection: Use
- The Law of Determinism Pinning (Flaky-to-Deterministic Conversion): An intermittent bug is not understood until you can trigger it on command. Never accept "passes 9 out of 10 runs" as verification. Strip away all sources of non-determinism—freeze wall-clock/monotonic time, pin PRNG/UUID seeds, and replace random concurrency timing with deterministic latch/barrier interleavings—until the bug fails 100% deterministically in a red test before writing the fix.
- The Red-Green-Revert Falsification Law: A fix is only proven when the deterministic reproducer fails (
RED) before the change, passes (GREEN) with the minimal causal fix, and fails again (RED) when the fix is temporarily reverted or when all diagnostic probes are stripped.
Invariant Rules
- Separate diagnostic probes from production commits. Diagnostic logging, tracing hooks, and temporary assertions must never be left behind as permanent code clutter or confused with the causal fix.
- Change exactly one independent variable per experiment. Mutating two configuration flags or two code paths in the same test run destroys causal attribution.
- Ban timing band-aids (
sleep,setTimeout, arbitrary retries) as fixes or reproducers. Usingsleep(100)to force or mask a race condition is timing luck, not synchronization. Use explicitPromise.withResolvers(), barriers, latches, or deterministicvirtual clocks. - Ban symptom-swallowing guards (
?.,try { ... } catch {},|| default) without upstream causal proof. If a value is unexpectedlyundefined, prove why the producer emittedundefinedinstead of silencing the consumer. - Enforce the 2-Strike Circuit Breaker. If two consecutive diagnostic probes fail to isolate the fault, or if a proposed fix fails to turn the deterministic reproducer green on the first pass, halt immediately, revert the workspace to clean
HEAD, and reformulate the hypothesis matrix from scratch. - Automate
git bisectpredicates with exit code discipline. A bisect runner script must return exit code0for good commits,1for the target bug, and125(git bisect skip) for unrelated build/setup failures so broken intermediate commits never corrupt the binary search. - Capture exact state transitions, not vague strings. Probes must log structured causal state (correlation ID, thread/task ID, monotonic sequence number, input hash, before/after state) rather than
console.log("here 1"). - Minimize the reproducer via Delta Debugging (
ddmin). Strip away unrelated middleware, UI layers, and payload fields until the failing input and execution path contain only the irreducible minimum required to trigger the fault. - Bridge from Mechanism (
scientific-fault-isolation) to Ownership (root-fix-gate). Once the surviving hypothesis proves how the state was corrupted, invokeroot-fix-gateif multiple layers could plausibly enforce the corrected invariant.
Execution Router
| Task Shape | Primary Workflow | Reference Contract |
| Mysterious crash, silent corruption, or multi-cause symptom | Differential Diagnosis | Differential Diagnosis Matrix |
| Regression across commits or corruption across multi-layer pipeline | Binary Search Isolation | Binary Search & Git Bisect |
| Intermittent race condition, Heisenbug, or flaky test | Deflake Race Condition | Determinism Pinning |
| Durable fault-isolation record generation & machine audit | Record Contract | scripts/fault_isolation_guard.py |
Mandatory Pre-Edit Interrogation Matrix
Before touching any production file to fix a non-trivial bug, answer these five questions with empirical evidence:
- Observation vs. Inference Check: What is the exact raw symptom (stack trace, HTTP status, corrupted row, race interleaving) versus your mental theory of what caused it?
- The 3-Hypothesis Challenge: What are $H_1$, $H_2$, and $H_3$? If your favored hypothesis ($H_1$) is 100% wrong, what is the next most likely physical mechanism?
- Discriminating Probe Design: What single read-only observation at midpoint boundary $M$ will produce Outcome $A$ if $H_1$ is true, Outcome $B$ if $H_2$ is true, and Outcome $C$ if $H_3$ is true?
- Non-Determinism Inventory: Does this code path read
Date.now(),Math.random(),crypto.randomUUID(), dictionary iteration order, network socket arrival order, or unawaited async callbacks? How have you pinned them in the test? - Reversibility & Falsification Check: If we revert your proposed 3-line fix while keeping the new regression test, does the test deterministically fail 10 out of 10 times?
Prohibited Anti-Patterns (Instant Rejection List)
- Shotgun Debugging (Edit-and-Pray): Modifying production code to "test a theory" without a prior falsification probe or deterministic failing test.
- Sleep-Driven Synchronization (
await new Promise(r => setTimeout(r, 250))): Adding arbitrary time delays to tests or production code to dodge an async race condition. - Blind Null-Shielding (
user?.profile?.balance ?? 0): Slapping optional chaining onto a crash site when the invariant dictatesuser.profilemust exist, converting a loud crash into silent financial/data corruption. - Multi-Variable Mutation: Changing a database query, a cache TTL, and an API timeout in a single debugging pass, making it impossible to know which change affected the symptom.
- Probe Pollution: Leaving
console.log("DEBUG"),print("HERE"), or commented-out experimental blocks in the working tree after fault isolation concludes. - Flaky Green Certification: Declaring a race condition "fixed" because a test suite passed once without pinning the concurrent execution order.
- Catch-and-Log Masking (
catch (err) { logger.warn(err); return []; }): Swallowing an unexplained exception to make an endpoint return HTTP 200 instead of isolating why the exception occurred.
Required Output & Review Workflow
Structure all non-trivial bug investigations and surgical fixes through this 4-phase discipline:
- Symptom & Space Partitioning ($O(\log N)$): State the exact failure signature and narrow the fault radius using temporal (
git bisect) or spatial (layer midpoint) binary search. - Differential Diagnosis Table ($H_1, H_2, H_3$) & Discriminating Probe: Present 3 falsifiable hypotheses, execute the minimal probe, and record the raw empirical output that kills 2 hypotheses and confirms the survivor.
- Deterministic Red Reproducer: Pin seeds, clocks, and concurrency barriers to produce a minimal test that fails 100% of the time under the surviving fault mechanism.
- Surgical Fix & Red-Green-Revert Verification: Apply the minimal causal fix (routing through
root-fix-gateif layer ownership is contested), strip all temporary probes, and verifyRED -> GREEN -> REVERT (RED) -> RESTORE (GREEN).
When a durable fault-isolation record is warranted, save a JSON assessment following the Fault Isolation Record Contract and audit it with:
npx anti-slop-engineering fault-isolation audit <record.json> --json
# or: python3 scripts/fault_isolation_guard.py audit <record.json> --jsonDomain References
- Surgical Debugging Playbook Suite: Central orchestration index for Microsoft/Meta differential diagnosis and deterministic concurrency isolation.
- Microsoft / Meta Differential Diagnosis Playbook: Hypothesis matrices, discriminating probes, Delta Debugging (
ddmin), and automatedgit bisectharnesses. - Deterministic Concurrency & Heisenbug Playbook: Schedule pinning, barrier orchestration, PRNG/clock freezing, and converting flaky race conditions into 100% deterministic tests.
- Differential Diagnosis Matrix: Templates and criteria for constructing mutually exclusive, falsifiable hypotheses and minimal probes.
- Binary Search & Git Bisect Patterns: Layer bisection protocols,
git bisect runexit code contracts (0,1,125), and data-pipeline midpoint probes. - Determinism Pinning Recipes: Concrete code recipes across TypeScript/Bun, Python, Go, and Rust for freezing time, seeds, and async interleavings.
- Fault Isolation Record Contract: JSON schema and verification rules for
scripts/fault_isolation_guard.py.
Failure Taxonomy
| Failure Mode | Observable Signal | Remediation |
| Shotgun debugging | Multiple production files edited before any root cause is proven | git checkout -- . to clean state; write 3 falsifiable hypotheses and a read-only probe |
| Non-falsifiable hypothesis | "Maybe there is a memory or timing issue somewhere in the worker" | Rewrite hypothesis with exact variable, line boundary, and measurable probe outcome |
| Heisenbug observer effect | Adding heavy console.log changes thread timing and hides the race | Replace I/O logs with in-memory ring-buffer trace or deterministic barrier latches |
| Bisect poisoning | git bisect lands on an unrelated broken build commit and blames the wrong PR | Return exit code 125 (git bisect skip) whenever build/compilation fails |
| Timing band-aid regression | Test passes locally with sleep(100) but fails under CI CPU contention | Replace wall-clock sleep with explicit Promise.withResolvers() / Barrier coordination |
| Symptom masking | Crash disappears after adding ?., but downstream database rows are corrupt | Revert null-shielding; bisect the producer boundary that emitted the invalid null state |
Delegated Skills
root-fix-gate: Oncescientific-fault-isolationproves the physical mechanism of the bug, delegate toroot-fix-gateif there is any ambiguity about which architectural layer or domain boundary should own the permanent invariant fix.paranoid-principal-architect: Apply when the isolated fault reveals a systemic concurrency flaw (TOCTOU, missing idempotency key, unbounded pool) requiring 10M-scale hardening.anti-slop-engineering: Follow parent BUILD/FIX gates, SRE guardrails, and clean-diff verification when committing the final surgical fix.
Completion and Limits
The task is complete when at least 3 falsifiable hypotheses have been evaluated, a discriminating probe has eliminated at least 2 hypotheses with empirical evidence, all non-deterministic factors (clocks, seeds, concurrency schedules) are pinned in a 100% reproducible red test, all temporary diagnostic probes are removed from production files, and the minimal fix passes Red-Green-Revert verification. An investigation may validly output pause if external production telemetry is inaccessible, or refuse if asked to ship an unverified shotgun workaround.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

