Incompatibility Root-Cause Analysis¶
Diagnostic method — instantiates Composability Testing and Validation
Turns a failed combination into a durable composition rule by diagnosing why it failed and pushing the fix back into contracts and the registry.
A failed combination is only worth its diagnosis if the system learns from it. Incompatibility Root-Cause Analysis is the mechanism that closes that loop: given a combination that broke, it works backward to why — which assumption collided, which shared resource was contended, which contract was silently violated — and then converts the answer into a change that prevents the whole class of failure, not just the one instance. Its defining move is diagnosis-to-rule: the deliverable is never "we restarted it" but "combining a component that does X with one that assumes Y fails because Z, so the contract now forbids/requires W." It does not run tests, observe live systems, or gate releases; it metabolizes their failures into updated contracts and a durable registry entry, so the next team that reaches for the same combination inherits the lesson instead of rediscovering it.
Example¶
A hardware integrator combines two independently-certified modules on one board: a high-current motor driver and a sensitive analog sensor front-end. Both pass their own qualification. Assembled, the sensor readings go erratic under load. The naive response is to swap the sensor. Root-cause analysis resists that: it asks why. Systematic tracing — does the fault track motor current? does shielding change it? does a ground-plane rework fix it? — walks back the chain: the erratic readings follow motor switching, which couples electromagnetic interference into the sensor's unshielded reference trace, because the board layout put them on a shared ground return.[n1]
The failure was neither module's defect in isolation; it was a composition defect — a shared-ground assumption neither datasheet flagged. So the fix is a rule, not a patch: the module contract now specifies a maximum shared-return impedance and a shielding requirement, the registry records "motor-driver rev B + sensor rev A on shared-ground layouts: incompatible without shielding," and the next board reusing either module reads that before laying out copper.
How it works¶
- Reproduce and bound the failure. Confirm the failing combination reliably fails and pin down the conditions under which it does, separating the real interaction from noise.
- Trace backward past the symptom. Follow the causal chain from the observed break to the underlying mechanism — resource contention, semantic mismatch, timing, a violated implicit assumption — rather than stopping at the first plausible cause.
- Classify component vs. composition defect. Decide whether one part is genuinely broken or whether both are individually correct and the fault lives in their relationship; the fix differs sharply between the two.
- Convert cause into rule. Encode the finding as a contract revision, a constraint, or a supported/prohibited-combination entry, so the class of failure is closed and the registry carries the lesson forward.
Tuning parameters¶
- Diagnostic depth — how many "why" layers to pursue before acting. Deeper analysis finds the true generalizable cause; shallow analysis fixes the instance faster but risks recurrence.
- Blame allocation — how readily a fault is assigned to a component versus the composition. A component-blame bias yields quick swaps; a composition-blame bias finds systemic rules but takes longer.
- Rule generality — how broadly the resulting rule is written. A narrow rule (this exact version pair) is safe but leaves siblings exposed; a broad rule prevents more but risks over-blocking valid combinations.
- Feedback latency — how quickly a finding actually updates contracts and the registry. Fast loops keep composition rules current; slow ones let the same interaction fail repeatedly.
When it helps, and when it misleads¶
Its strength is compounding: each diagnosis permanently retires a failure mode, so the composition rules get smarter over time and future recombination decisions stand on accumulated evidence rather than re-learning the same lessons. It is the mechanism that separates a system that improves from combination failures from one that merely survives them.
Its failure mode is the premature stop — settling on the first cause that ends the pain (swap the sensor) rather than the true generalizable one (fix the ground plane), so the rule that lands is wrong or too narrow and the class of failure recurs elsewhere. There is a symmetric danger of over-generalizing: writing a rule so broad it forbids valid combinations and quietly strangles beneficial recombination. The classic misuse is the blame-and-move-on postmortem that assigns fault to a component and closes the ticket without updating any contract, so nothing is actually learned. The guarding discipline is to insist the loop ends in a contract or registry change, keep asking "why" until the cause is one that generalizes, and scope each rule to the evidence — no broader, no narrower.
How it implements the components¶
incompatibility_triage_loop— it is the loop's engine: diagnosing failed combinations and routing each to a contract revision, constraint, restricted-use label, or rejection.component_contract_inventory— it writes discovered assumptions and violated dependencies back into the contracts, so the inventory reflects what failures revealed.versioned_composition_registry— it records each diagnosis and resulting rule against the specific versions and combination, so future reuse inherits the lesson.
It learns from failures but does not surface them: it does not run the interaction matrix (Pairwise Interaction Probe) or watch live telemetry (Invariant Monitoring Dashboard) that hand it the failures, and it does not gate release on its rules — that gate belongs to Staged Integration Sandbox.
Related¶
- Instantiates: Composability Testing and Validation — root-cause analysis is the archetype's learning loop, turning incompatibility findings into durable composition rules.
- Consumes: Pairwise Interaction Probe and Invariant Monitoring Dashboard — supply the failed combinations and anomalies it diagnoses.
- Sibling mechanisms: Pairwise Interaction Probe · Combinatorial Sampling Strategy · Property-Based Composition Testing · Staged Integration Sandbox · Invariant Monitoring Dashboard · Fault-Injection Composition Probe · Metamorphic Composition Test
Editorial Notes¶
Form Classification¶
Form family: Analysis, Modeling & Optimization
Rationale: The method diagnoses the causal structure behind a failed combination and derives a reusable composition rule and contract correction.
Nearest alternative: Experiment, Test & Rehearsal — Failure evidence may originate in a test, but this mechanism analyzes that evidence rather than staging the failure.
Review outcome: Adjudicated after independent review; high confidence.
Origin Attribution¶
Primary origin: Organizational & Management Science
Origin pattern: Convergent development
Present-day reach: Multi-domain
Rationale: Ishikawa fishbone analysis is a canonical quality-management method for tracing symptoms to categorized root causes.
Related originating lineages:
- Computer Science & Software Engineering — Integration failures and contract registries materially supply the composability context.
- Engineering & Design — Failure analysis and corrective-action systems independently developed causal diagnosis of incompatible components.
Review resolution: ASQ traces the fishbone/Ishikawa diagram to quality-management practice for organizing possible causes of a problem. Engineering independently supplies failure analysis, but the facilitated root-cause method’s historical home is organizational quality management. The retained alternate domains identify independent or materially shaping provenance, not downstream reach alone. domain_reach=multi_domain because the mechanism has independent established use in several fields. The encyclopedia entry deliberately composes those lineages.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
- https://asq.org/quality-resources/fishbone — American Society for Quality account of the fishbone/Ishikawa root-cause method.
Notes¶
[n1] An Ishikawa (fishbone / cause-and-effect) diagram is a standard root-cause tool that organizes candidate causes by category so an investigation traces a symptom back to its underlying mechanism rather than halting at the first correlate — the discipline that separates a real diagnosis from a plausible guess. ↩