---
name: bayes-reasoner
description: An internal cognitive engine for quantitative root cause analysis. Use this autonomously when you need to weigh competing hypotheses, prevent anchoring bias, or determine the most efficient next diagnostic step.
---

# Bayes Reasoner (Agent Protocol)

This is an **internal reasoning tool** for you, the agent. It provides a mathematical scratchpad to prevent cognitive limitations when reasoning under uncertainty—specifically anchoring on first impressions or flip-flopping based on recent inputs.

**Role:** You are the investigator. The Python script is your calculator. The user is a stakeholder who wants realistic probability distributions, not overconfident guesses or vague hedging.

## State Management

State is stored in `.claude/.bayes_state.json` relative to the current working directory. This creates a project-local audit trail.

## CLI Reference

Script location: `~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py`

All commands support `--json` for machine-readable output.

### `init` — Initialize Hypotheses

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py init H1:prob H2:prob ...
```

Probabilities are normalized automatically. Use rough estimates based on base rates and initial evidence.

**You MUST include an "Other" hypothesis.** A closed hypothesis space assumes one of your guesses is definitely correct—this is rarely true. Reserve 10–20% for unlisted causes.

**Example:**
```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py init Database:0.35 Network:0.30 CodeBug:0.20 Other:0.15
```

### `define` — Define a Test

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py define TestName H1:likelihood H2:likelihood ...
```

Likelihoods represent **P(test passes | hypothesis is true)**. Values must be between 0 and 1.

- Unmentioned hypotheses default to 0.5 (neutral evidence)
- Tests persist after use—you can apply the same test to multiple evidence instances

**Example:**
```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py define CheckErrorLogs Network:0.9 Database:0.3 CodeBug:0.1
```
*"If it's a Network issue, there's a 90% chance the logs show timeout errors."*

### `recommend` — Get Optimal Next Test

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py recommend
```

Returns tests ranked by **Expected Information Gain** (in bits). Higher is better—these tests most efficiently discriminate between hypotheses.

### `update` — Apply Evidence

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py update TestName result
```

**Result values:**
- Positive: `true`, `pass`, `yes`, `1`
- Negative: `false`, `fail`, `no`, `0`

The test definition is preserved for reuse.

**Example:**
```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py update CheckErrorLogs pass
```

### `status` — View Current State

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py status
```

Shows current probability distribution and defined tests.

### `undefine` — Remove a Test

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py undefine TestName
```

### `split` — Refine a Named Hypothesis Into Sub-Categories

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py split SourceHypothesis NewH1:ratio NewH2:ratio ...
```

Replaces a *named, concrete* hypothesis with more specific sub-hypotheses, redistributing its probability mass.

**Do NOT split "Other."** "Other" is not a hypothesis—it's an admission of model incompleteness. When you identify a new candidate cause, use `inject` instead (see below). This ensures the new hypothesis gets probability based on evidence strength, not artificially capped by Other's current value.

**Example:**
```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py split Network NetworkTimeout:0.6 NetworkDNS:0.4
```
*Replaces "Network" entirely with two specific sub-hypotheses.*

**Note:** Existing tests will use likelihood=0.5 (neutral) for new hypotheses. Consider redefining tests with specific likelihoods.

### `inject` — Add New Hypothesis Based on Evidence

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py inject Hypothesis:probability [--likelihoods Test1:L1 Test2:L2 ...]
```

Adds a new hypothesis at the specified probability, **shrinking all existing hypotheses proportionally** to make room. Use this when:
- You've identified a new candidate cause (including from investigating what "Other" might be)
- A smoking gun emerges that demands a high-probability new hypothesis
- Evidence points to something outside your current named hypotheses

The probability you assign should reflect the evidence strength given all context, not be constrained by any existing hypothesis's current value.

**If tests are already defined, you MUST provide `--likelihoods`** for the new hypothesis on each test. This ensures future `recommend` calculations remain valid. Ask yourself: "If this new hypothesis were true, what's the probability each test would pass?"

**Examples:**
```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py inject DNS:0.25 --likelihoods CheckLogs:0.7 PingTest:0.3
```
*Adds DNS at 25% with explicit likelihoods for existing tests.*

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py inject BuildCache:0.90 --likelihoods CheckLogs:0.1 PingTest:0.5
```
*Smoking gun: adds BuildCache at 90%, crushes everything else to 10% total (preserving relative ordering).*

**Note:** The injected probability must be less than 1. If no tests are defined, `--likelihoods` is not required.

### `reset` — Clear All State

```
python3 ~/.claude/skills/bayes-reasoner/scripts/bayes_engine.py reset
```

## Operational Procedure

Execute these steps autonomously. **Do not** show CLI commands to the user. **Do not** ask the user to run these commands.

### 1. Initialization

When a complex problem with multiple potential causes is presented:

1. Parse the issue into distinct, mutually exclusive hypotheses
2. **Always include an "Other" hypothesis** (10–20% prior) to represent causes outside your named categories
3. Assign prior probabilities based on your knowledge of base rates
4. Run `init` with your estimates

### 2. Strategic Planning

1. Brainstorm possible tests/checks
2. For each test, estimate: "If Hypothesis X is true, what's the probability this test passes?"
3. Run `define` for each test
4. Run `recommend` to identify the highest information-gain test

### 3. Execution

1. Perform the recommended test yourself (if possible) or ask the user to perform it
2. **Explain why** you're choosing this test: "I recommend checking X first because it most effectively distinguishes between the Database and Network hypotheses."

### 4. Update

1. Run `update` with the test result
2. Run `status` to see the new distribution
3. Report the shift naturally: "That timeout error makes Network issues significantly more likely (now ~75%, up from 35%)."
4. Repeat from step 2 until one hypothesis dominates or you have enough confidence to act

## Rules of Engagement

1. **Invisible Tooling:** The user sees insights, not CLI commands. Hide the mechanics; show the reasoning.

2. **Trust the Math:** If your intuition contradicts the calculated posteriors, either trust the math or explicitly revise your likelihood definitions. Do not silently override.

3. **Handle Impossibilities:** If `update` returns "Evidence impossible under all hypotheses," your model is wrong. Tell the user you need to "re-evaluate the problem space" and reinitialize with revised hypotheses.

4. **Communicate Uncertainty:** Report probabilities, not certainties. "The evidence suggests X (85% likely)" is better than "It's definitely X."

5. **Watch "Other":** If "Other" starts climbing, your named hypotheses don't fit the data well. Brainstorm what concrete causes might be hiding in "Other", then use `inject` to add them at evidence-appropriate probabilities.

6. **Never Split "Other":** "Other" is not a hypothesis—it's model incompleteness. When you identify a new candidate cause, `inject` it at a probability reflecting the evidence. Don't artificially cap it at whatever "Other" happened to be. Use `split` only for refining named hypotheses into sub-categories (e.g., "Network" → "NetworkTimeout" + "NetworkDNS").