/by-causal-reasoning

id: "skill_6f0661a7e4024d0aab430f1b236e282f"
name: "by-causal-reasoning"
display-name: "BY Causal Reasoning"
short-description: "Generate ranked mechanistic hypotheses for protein-design failure patterns, each anchored in knowledge-graph evidence with confidence tiers and falsifiable predictions. Use when a campaign has been statistically diagnosed and you need to explain WHY designs failed before committing the next round of compute."
category: "analysis"
keywords: "causal reasoning, mechanistic hypothesis, root cause analysis, evidence grading, failure mechanisms, knowledge graph, hypothesis ranking, falsifiable prediction, parsimony, post-mortem"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools:
  - "mcp__by-knowledge__knowledge_query_similar"
  - "mcp__by-knowledge__knowledge_scaffold_rankings"
  - "mcp__by-knowledge__knowledge_get_recommendations"
  - "mcp__by-knowledge__knowledge_store_failure"

BY Causal Reasoning Skill

Most "AI scientist" demos fake reasoning by chaining LLM calls and calling the chain a hypothesis. This skill does the opposite: it constrains the LLM with **structured evidence retrieved from the BY knowledge graph** and forces every claim to cite an existing entity with a defined evidence tier. The output is a short, ranked list of mechanistic hypotheses — each one falsifiable, each one traceable to a campaign, paper, or prior failure record.

It sits between **statistical diagnosis** (which says *which* features discriminate PASS from FAIL) and **campaign optimization** (which spends new compute). Without this step, the optimizer can only tweak thresholds; with it, the optimizer can target the underlying mechanism.

---

When to Use This Skill

Use this skill when:

• ✅ **`by-failure-diagnosis` has produced a discriminating-features ranking** and you need to translate statistical signals into mechanistic claims before the next round.
• ✅ **`by-epitope-analysis` is available** so structural context (topology, hotspot residues, druggability) can be merged with statistical signals.
• ✅ **You are about to call `by-campaign-optimizer`** for round N+1 — the optimizer's parameter changes should target a named mechanism, not a vibe.
• ✅ **A campaign shows an unexpected (non-trivial) pattern** — e.g. high ipSAE designs are failing at the lab stage, or pass rate dropped vs the prior round with no parameter change.
• ✅ **The user explicitly asks** "why are my designs failing at this *mechanism*?", "what's the underlying cause?", or "rank possible explanations".
• ✅ **You have access to `by-knowledge` data** — querying without a populated graph yields hypotheses with no evidence, which violates the skill contract.

Do NOT use this skill when:

• ❌ **As a substitute for actually running experiments.** Hypotheses are pointers to experiments, not conclusions. If the user asks "is this the cause?", the answer is *"the falsifiable prediction is X — run that assay to confirm"*, not *"yes"*.
• ❌ **Without evidence citations.** Every claim must reference at least one knowledge-graph entity (`campaign_<id>` or `failure_<id>`). A "hypothesis" with no evidence is a guess — flag it as SPECULATIVE or refuse to emit it.
• ❌ **To generate more than 5 hypotheses.** Parsimony is enforced: 3-5 is the cap. More than 5 means the agent is laundering uncertainty as breadth. If the diagnosis genuinely supports more candidates, that is a signal to call `by-hypothesis-debate` for adversarial pruning, not to inflate the list.
• ❌ **For per-residue redesign rationale.** That is structural, not statistical — use `by-epitope-analysis` instead.
• ❌ **When the campaign has fewer than 30 scored designs.** Statistical signals are too noisy; the hypotheses will not be reliably evidenced.
• ❌ **For pre-campaign target selection.** That is `by-research` territory; this skill explains past failures, not future opportunities.
• ❌ **When the knowledge graph is empty (0 campaigns, 0 failures recorded).** The skill cannot ground hypotheses in evidence — refuse to run, ask user to populate `by-knowledge` first.

---

Quick Start

Typical invocation: feed the diagnosis + epitope outputs from a campaign, let the skill query `by-knowledge` for evidence, and emit ranked hypotheses.

python3 scripts/generate_hypotheses.py \
  --diagnosis campaigns/tnf/run01/diagnosis.json \
  --epitope campaigns/tnf/run01/hotspots.json \
  --target "TNF-alpha" \
  --modality "VHH" \
  --max-hypotheses 4 \
  --out campaigns/tnf/run01/hypotheses.json \
  --trail campaigns/tnf/run01/evidence_trail.md

Expected console output:

✓ Loaded diagnosis: 9 features tested, 3 significant
✓ Loaded epitope: 6 hotspots, topology=flat, druggability=moderate
✓ Queried knowledge graph: 12 similar campaigns, 4 matching failures
✓ Generated 4 hypotheses (1 HIGH, 2 MEDIUM, 1 SPECULATIVE)
✓ Wrote campaigns/tnf/run01/hypotheses.json
✓ Wrote campaigns/tnf/run01/evidence_trail.md

The resulting `hypotheses.json` is a JSON array of at most 5 ordered hypotheses; each carries claim text, supporting + contradicting evidence with entity IDs, a confidence label, and a falsifiable prediction.

To validate hypotheses after generation (verify every cited entity exists in the graph and the evidence tier was assigned correctly):

python3 scripts/score_hypothesis_evidence.py \
  --hypotheses campaigns/tnf/run01/hypotheses.json \
  --out campaigns/tnf/run01/hypotheses_scored.json

---

Installation

| Software | Version | License | Commercial Use | Installation Command | |----------|---------|---------|----------------|---------------------| | Python | ≥3.10 | PSF | ✅ Permitted | preinstalled | | `mcp` SDK | ≥1.0 | MIT | ✅ Permitted | `pip install mcp` | | `pydantic` (optional, schema validation) | ≥2.0 | MIT | ✅ Permitted | `pip install pydantic` | | `jsonschema` (optional, output validation) | ≥4.0 | MIT | ✅ Permitted | `pip install jsonschema` |

**License Compliance:** All packages permit commercial use in AI applic