by-causal-reasoning

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.