@polderlabs/bizar 10.6.0 → 10.7.0

package/cli/install/postinstall.mjs

@@ -11,10 +11,10 @@ import { join } from 'node:path';
 import { resolveClaudeDir, PATHS } from './paths.mjs';
 
 const AGENT_FILES = [
-  'odin.md', 'vor.md', 'frigg.md', 'quick.md',
-  'mimir.md', 'heimdall.md', 'hermod.md', 'thor.md', 'baldr.md',
-  'tyr.md', 'vidarr.md', 'forseti.md',
-  'semble-search.md',
+  'mike.md', 'janet.md', 'susan.md', 'pam.md',
+  'greg.md', 'brenda.md', 'steve.md', 'todd.md', 'brad.md',
+  'karen.md', 'carl.md', 'linda.md',
+  'oscar.md',
 ];
 
 /**

package/cli/plow-through.test.mjs

@@ -11,10 +11,11 @@ import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = join(__dirname, '..');
-const CMD_PATH = join(PROJECT_ROOT, 'config', 'commands', 'plow-through.md');
+// F-107: slash commands canonical at .claude/commands/. Legacy config/commands/ removed (Cline-era).
+const CMD_PATH = join(PROJECT_ROOT, '.claude', 'commands', 'plow-through.md');
 
 describe('/plow-through command file', () => {
-  test('file exists at config/commands/plow-through.md', () => {
+  test('file exists at .claude/commands/plow-through.md', () => {
     assert.equal(existsSync(CMD_PATH), true, 'plow-through.md must exist');
   });
 
@@ -23,10 +24,10 @@ describe('/plow-through command file', () => {
     assert.match(content, /^---\ndescription:/m, 'frontmatter must have description');
   });
 
-  test('YAML frontmatter has agent field set to odin', () => {
-    const content = readFileSync(CMD_PATH, 'utf8');
-    assert.match(content, /^---\n.*\nagent: odin$/ms, 'frontmatter agent must be odin');
-  });
+  // F-107: legacy `agent: mike` frontmatter field was removed when slash
+  // commands were migrated to Claude Code's `run_in_background: true`
+  // Agent dispatch model. Routed agents are now inferred from the
+  // command body via the thinking-route hook.
 
   test('body has content (more than 5 lines)', () => {
     const content = readFileSync(CMD_PATH, 'utf8');

package/cli/prompts.mjs

@@ -1,17 +1,17 @@
 import inquirer from 'inquirer';
 
 const AGENTS_LIST = [
-  { name: 'Odin ᛟ  — MiniMax-M3 (Router)', value: 'odin.md', checked: true },
-  { name: 'Frigg ᚠ  — DeepSeek (Codebase Q&A, read-only)', value: 'frigg.md', checked: true },
-  { name: 'Vör ᚡ  — DeepSeek (Clarification)', value: 'vor.md', checked: true },
-  { name: 'Mimir ᛗ — DeepSeek (Research)', value: 'mimir.md', checked: true },
-  { name: 'Heimdall ᚹ — DeepSeek (Simple tasks)', value: 'heimdall.md', checked: true },
-  { name: 'Hermod ᚱ — MiniMax-M2.7 (Git ops)', value: 'hermod.md', checked: true },
-  { name: 'Thor ᚦ  — MiniMax-M2.7 (Mid impl.)', value: 'thor.md', checked: true },
-  { name: 'Baldr ᛒ  — MiniMax-M2.7 (Design)', value: 'baldr.md', checked: true },
-  { name: 'Tyr ᛏ  — MiniMax-M3 (Complex impl.)', value: 'tyr.md', checked: true },
-  { name: 'Vidarr ᛉ — MiniMax-M3 (Last resort)', value: 'vidarr.md', checked: false },
-  { name: 'Forseti ᚨ — MiniMax-M3 (Plan audit)', value: 'forseti.md', checked: true },
+  { name: 'Odin ᛟ  — MiniMax-M3 (Router)', value: 'mike.md', checked: true },
+  { name: 'Frigg ᚠ  — DeepSeek (Codebase Q&A, read-only)', value: 'susan.md', checked: true },
+  { name: 'Vör ᚡ  — DeepSeek (Clarification)', value: 'janet.md', checked: true },
+  { name: 'Mimir ᛗ — DeepSeek (Research)', value: 'greg.md', checked: true },
+  { name: 'Heimdall ᚹ — DeepSeek (Simple tasks)', value: 'brenda.md', checked: true },
+  { name: 'Hermod ᚱ — MiniMax-M2.7 (Git ops)', value: 'steve.md', checked: true },
+  { name: 'Thor ᚦ  — MiniMax-M2.7 (Mid impl.)', value: 'todd.md', checked: true },
+  { name: 'Baldr ᛒ  — MiniMax-M2.7 (Design)', value: 'brad.md', checked: true },
+  { name: 'Tyr ᛏ  — MiniMax-M3 (Complex impl.)', value: 'karen.md', checked: true },
+  { name: 'Vidarr ᛉ — MiniMax-M3 (Last resort)', value: 'carl.md', checked: false },
+  { name: 'Forseti ᚨ — MiniMax-M3 (Plan audit)', value: 'linda.md', checked: true },
 ];
 
 export async function promptComponents() {

package/cli/provision.mjs

@@ -430,21 +430,10 @@ function syncDir(srcDir, destDir, opts = {}) {
   return { copied, skipped };
 }
 
-export async function syncAgentFiles({ dryRun = false } = {}) {
-  const src = join(REPO_ROOT, 'config', 'agents');
-  const dest = CLAUDE_AGENTS_DIR;
-  if (!existsSync(src)) return { ok: true, message: `no agents source at ${src}`, copied: 0, skipped: 0 };
-  if (dryRun) return { ok: true, message: `[dry-run] would sync ${src} → ${dest}` };
-  ensureDir(dest); ensureDir(join(dest, '_shared'));
-  let { copied, skipped } = syncDir(src, dest, { filter: n => n.endsWith('.md') });
-  const sharedSrc = join(src, '_shared');
-  if (existsSync(sharedSrc)) {
-    for (const entry of readdirSync(sharedSrc, { withFileTypes: true })) {
-      if (entry.isFile()) { copyFileSync(join(sharedSrc, entry.name), join(dest, '_shared', entry.name)); copied++; }
-    }
-  }
-  return { ok: true, message: `${copied} agent(s) synced (${skipped} kept)`, copied, skipped };
-}
+// F-107: syncAgentFiles removed. Agent definitions live at
+// .claude/agents/ (Claude Code canonical) — they were never sourced
+// from config/agents/ in Claude Code era, and the legacy source dir
+// was deleted.
 
 export async function syncSkillFiles({ dryRun = false } = {}) {
   const src = join(REPO_ROOT, 'config', 'skills');
@@ -704,7 +693,6 @@ export async function runProvision(opts = {}) {
     return r;
   };
 
-  await runStep('Syncing agents',    () => syncAgentFiles({ dryRun, force }));
   await runStep('Syncing skills',    () => syncSkillFiles({ dryRun, force }));
   await runStep('Syncing commands',   () => syncCommandFiles({ dryRun, force }));
   await runStep('Syncing rules',      () => syncRulesFiles({ dryRun, force }));

package/config/skills/bizar/SKILL.md

@@ -253,7 +253,7 @@ Single-key mode is unchanged — if only `MINIMAX_API_KEY` is set (or no key rot
 
 ## Verbose Agent Baseline Reference
 
-> The 12 always-on rules in `config/agents/_shared/AGENT_BASELINE.md`
+> The 12 always-on rules in `.claude/agents/_shared/AGENT_BASELINE.md`
 > are auto-loaded into every agent session at startup. The full prose
 > for each rule lives below — read this section when an agent needs
 > the full rationale, examples, and decision tree for a given rule.

package/config/skills/skillopt/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: skillopt
+description: Microsoft's SkillOpt trains skill files via rollouts + reflection against a frozen target model. Install with `pip install skillopt` and produce a `best_skill.md`. Always human-review.
+---
+
+# SkillOpt Workflow
+
+## Overview
+
+SkillOpt (microsoft/SkillOpt, MIT-licensed) is a Microsoft Research Python tool that **optimizes skill files for a specific target model**. Given a starting `SKILL.md`, a target model (frozen), a benchmark of inputs, and a reward signal, SkillOpt runs a rollout → reflect → aggregate → select → update → evaluate loop and emits a `best_skill.md` artifact that scores higher against the held-out validation gate.
+
+It is *not* a general prompt editor and *not* a free-form rewriting tool. It is a closed-loop optimizer: it changes the skill text, runs the agent under the new skill against the benchmark, measures reward, and keeps mutations that improve the score.
+
+**Core Principle:** SkillOpt trains a skill file the way you'd fine-tune a model — with a held-out validation gate, a frozen target, and a reward signal — not by hand-tweaking prose. Don't commit the output without human review; treat `best_skill.md` as a candidate, not a verdict.
+
+## When to Use
+
+- A skill's quality is measurably degrading on a benchmark (success rate dropping, regression in eval)
+- You have a benchmark of representative inputs and a reward signal (task success / rubric score / pass-rate)
+- You want to A/B a new skill variant against the current one against the same target model
+- A skill has grown organically past ~200 lines and you suspect prose bloat is hurting recall
+
+Decision flow:
+
+```
+Skill quality question?
+  → Do you have a benchmark + reward + frozen target model? → no → DON'T RUN SKILLOPT (you can't measure without them)
+  → Is the skill underperforming on the gate? → no → no work to do
+  → Yes to both → see the 6-phase loop below
+```
+
+## When NOT to Use
+
+- **No benchmark, no reward, no frozen target.** SkillOpt needs all three. If any is missing, the loop has nothing to optimize against — you'll burn compute on something you can't evaluate. Compose the benchmark first or skip SkillOpt entirely.
+- **For a one-off skill polish.** SkillOpt is a multi-rollout loop with token cost on the order of dozens to hundreds of completions. For "rewrite this paragraph to be clearer," edit the skill by hand. Reach for SkillOpt when you have evidence the skill underperforms and a way to measure the fix.
+- **On a non-frozen target model.** If the target model is updating daily, the rollout scores are non-reproducible and the held-out gate stops meaning anything. Pin the model version and don't retrain against a moving target.
+- **Without human review of `best_skill.md`.** SkillOpt optimizes the reward signal — that is not the same as "is this skill correct, well-bounded, and aligned with what we want the agent to do." A skill that scores higher on the rubric can still be narrower, more brittle, or subtly off-vibe. Always review before committing.
+
+## The 6-Phase Loop
+
+```
+┌─ Phase 1: Rollout        ─ run the agent under the current skill against benchmark inputs
+│
+├─ Phase 2: Reflect        ─ for each rollout, capture which skill instructions helped vs hurt
+│
+├─ Phase 3: Aggregate      ─ across all rollouts, find recurring failure modes and structural patterns
+│
+├─ Phase 4: Select         ─ choose one mutation hypothesis (a concrete edit) to try next
+│
+├─ Phase 5: Update         ─ apply the mutation to produce a candidate skill
+│
+└─ Phase 6: Evaluate       ─ run the candidate against the HELD-OUT validation set; keep if it improves, drop if not
+                              ↑                                                              │
+                              └────────────── next iteration reuses the kept variant ─────────┘
+```
+
+### Phase 1 — Rollout
+
+Run the agent under the **frozen target model** with the current skill against the benchmark. Capture outputs + per-input scores. Don't peek at the validation set during this phase.
+
+### Phase 2 — Reflect
+
+For each rollout, ask: which lines of the skill contributed to the success or failure? Mark helpful / neutral / harmful spans. This is the closest you get to a teacher signal without a human labeler.
+
+### Phase 3 — Aggregate
+
+Across all rollouts this iteration, find the recurring failure modes. If 4 of 5 failures on a particular input pattern come from the same missing instruction in the skill, that's the highest-leverage next mutation.
+
+### Phase 4 — Select
+
+Pick **one** mutation to try. SkillOpt is not a search-and-replace shotgun; it's one edit per round. Co-edits entangle effects and make the held-out gate stop carrying signal.
+
+### Phase 5 — Update
+
+Apply the mutation. Save the candidate as a sibling file (e.g. `candidate-3.md`); never overwrite `SKILL.md` mid-loop.
+
+### Phase 6 — Evaluate
+
+Run the candidate against the **held-out validation set** (never been seen during Phases 1–5). If it improves the held-out gate, promote it to the next iteration's starting point. If it regresses, drop it and try a different mutation. Do not cherry-pick from a known input; the held-out gate is what makes the loop trustworthy.
+
+## How Bizar Agents Use It
+
+```bash
+# 1. Install (do this once per machine)
+pip install skillopt
+
+# 2. Set up a benchmark directory (you write this — SkillOpt doesn't generate it)
+#    benchmark/
+#    ├── inputs.jsonl       # one prompt per line, hold-out set included
+#    ├── reward.py          # your scoring fn: takes (prompt, completion) → float
+#    └── target_model.json  # the frozen target model spec (id + version pin)
+
+# 3. Run the loop against a draft skill
+python -m skillopt.cli optimize \
+  --skill config/skills/thinking-some-skill/SKILL.md \
+  --benchmark ./benchmark \
+  --out ./skillopt-out
+
+# 4. Inspect the output before committing anything
+ls skillopt-out/
+cat skillopt-out/best_skill.md
+diff config/skills/thinking-some-skill/SKILL.md skillopt-out/best_skill.md
+
+# 5. If the diff is genuinely better (held-out improvement + human review passes),
+#    replace the source. Otherwise discard and tune the benchmark.
+cp skillopt-out/best_skill.md config/skills/thinking-some-skill/SKILL.md
+```
+
+We do **not** vendor SkillOpt into the Bizar JS harness — the tool lives in Python (`pip install skillopt`), runs offline, and writes a markdown artifact. The Bizar loop is: write draft → run SkillOpt → human review `best_skill.md` → commit if better.
+
+## Pitfalls
+
+- **Don't retrain daily.** The target model is frozen for a reason; if your benchmark doesn't drift, the skill shouldn't either. Bumping SkillOpt runs on every PR turns the skill into a moving target the agent can't build a stable intuition against.
+- **Don't bypass the held-out gate.** It's tempting to "peek" at validation items to bias the mutation — that converts the loop into a curve-fit on a small set and the held-out number stops meaning anything. Hold-out integrity is the whole point.
+- **Never auto-commit `best_skill.md`.** It is a *candidate*. The reward signal optimizes task success; it does not optimize for tone, scope, or alignment with sibling skills in the same family. A/B test in shadow, then promote deliberately.
+- **Don't use SkillOpt on skills you don't have a benchmark for.** If the input space and reward are unknown, you're optimizing prose against nothing and will learn something — just not something useful.
+- **Don't optimize `thinking-*` skills together as one bundle.** They share front-matter shape but address different problem types; co-optimizing entangles their effects and makes individual improvements hard to attribute.
+
+## Relationship to Bizar's Existing Skill Pipeline
+
+| Concern | Owner |
+|---|---|
+| What skills ship | `config/skills/<name>/SKILL.md` (canonical, provisioned) |
+| Provision to user | `cli/provision.mjs:syncConfigExtras` + `writeBizarSkillLock` |
+| Skill discovery at runtime | `~/.claude/skills/<name>/SKILL.md` (provisioned mirror) |
+| Offline quality loop | SkillOpt (this skill) — run on a draft, produce `best_skill.md`, human-promote |
+| Editing prose by hand | You + your editor — fine for one-off tweaks, don't loop it |
+
+SkillOpt is a **research-quality tool** for the rare case where you have the benchmark, the reward, and the time. For 90% of skill edits, just write it well.

package/config/skills/thinking-archetypes/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: thinking-archetypes
+description: Use when the same problem keeps recurring despite fixes, growth stalled with no obvious cause, or a quick fix made things worse—match it to a known structural pattern instead of re-diagnosing.
+---
+
+# Systems Archetypes
+
+## Overview
+
+Systems archetypes (Peter Senge, "The Fifth Discipline") are recurring structural patterns. Like design patterns in software, once you recognize one you can predict where it leads and where to intervene. Most stubborn, recurring problems aren't unique—they're an instance of a known pattern, and the pattern names the leverage point.
+
+**Core Principle:** A recurring problem usually has a structural pattern. Match the pattern and the intervention follows.
+
+## Trigger Card
+
+When the same problem keeps recurring despite multiple fixes:
+
+1. **Describe the problem neutrally** — symptoms, what's been tried, what keeps coming back.
+2. **Match to an archetype** using the Quick Reference Card below (Fixes That Fail, Shifting the Burden, Limits to Growth, Tragedy of the Commons, Escalation, Success to the Successful, Growth and Underinvestment).
+3. **Intervene at the structure, not the symptom** — use the Key Question for that archetype.
+
+If no archetype fits after a genuine look, don't force one — drop to `thinking-systems` and map from scratch. For a first-time one-off problem, just fix it.
+
+## When to Use
+
+- The same problem keeps recurring despite multiple "fixes"
+- A quick fix made things worse over time
+- Growth stalled without an obvious cause
+- A shared resource (CI, staging, a cache, a service quota) keeps degrading
+- Two efforts are escalating against each other (duplicated services, alert/threshold arms races)
+
+```
+Problem keeps recurring despite fixes?  → match an archetype
+Quick fix made it worse?                → match an archetype
+Growth hit an invisible ceiling?        → match an archetype
+Shared resource degrading?              → match an archetype
+```
+
+## When NOT to Use
+
+- **You need to map the system from scratch** (components, interactions, emergent behavior) — use `thinking-systems` instead. Archetypes are pattern-matching shortcuts for recurring structures; if the system is unfamiliar, map it first, then see if an archetype fits.
+- **You've found the pattern and need to know where to intervene** — use `thinking-leverage-points` (Meadows' hierarchy). Archetypes name the structure; leverage-points tell you where in that structure to act for maximum effect.
+- A first-time, one-off problem with a clear cause → just fix it; there's no recurring structure to match.
+- No candidate archetype fits after a genuine look → don't force one. Drop to `thinking-systems` and map the actual structure from scratch.
+- You need to localize a specific faulty codepath → use a hypothesis differential, not pattern-matching.
+
+## Quick Reference Card
+
+Match the symptom to the pattern; the Key Question points at the leverage.
+
+| Archetype | Structure | Recognize it by | Key Question (leverage) |
+|-----------|-----------|-----------------|-------------------------|
+| **Fixes That Fail** | Quick fix relieves symptom but a delayed side effect makes it worse | "We fixed this last quarter, why is it back?"; the fix needs ever-larger doses | "What side effect will this fix create?" |
+| **Shifting the Burden** | A symptomatic workaround is used instead of the fundamental fix, creating dependency | Permanent workarounds; "we know the real fix but have no time"; the real capability is atrophying | "What capability are we not building by leaning on this workaround?" |
+| **Limits to Growth** | A reinforcing growth loop hits a balancing constraint | Strong growth that plateaued; more effort, diminishing returns; a resource maxed out | "What will limit us at 10x scale?" |
+| **Tragedy of the Commons** | Each actor gains by using a shared resource; collective overuse depletes it | Shared CI/staging/cache/quota degrading; everyone optimizes locally; no clear owner | "Who owns the long-term health of this resource?" |
+| **Escalation** | Two parties react to each other's moves in a competitive spiral | "They did X so we must do Y"; arms-race dynamics; each side feels defensive | "Can we change the game instead of playing it harder?" |
+| **Success to the Successful** | Initial success grants more resources, compounding advantage and starving alternatives | Past success is the main predictor of new investment; experiments starved to feed the incumbent | "Are we starving future successes to feed current ones?" |
+| **Growth and Underinvestment** | Demand grows toward a limit; capacity investment is delayed until performance degrades into crisis | Reactive investment after the incident; chronic "good enough for now" | "What fails if we grow 50% without adding capacity now?" |
+
+## Software Examples (per archetype)
+
+- **Fixes That Fail:** Adding servers to mask a memory leak → cost spirals, leak remains. Silencing alerts → system degrades until outage.
+- **Shifting the Burden:** Ops manually intervening forever instead of automating; feature flags hiding bugs that never get fixed.
+- **Limits to Growth:** Velocity drops as the codebase grows (complexity limit); adding engineers doesn't speed delivery (coordination overhead).
+- **Tragedy of the Commons:** Teams overload shared CI → everyone's builds slow; cloud costs spike as nobody cleans up resources.
+- **Escalation:** Microservice teams duplicating functionality in response to each other; ever-stricter alert thresholds chasing each other.
+- **Success to the Successful:** Legacy monolith gets all attention so the new architecture never matures.
+- **Growth and Underinvestment:** Database not upgraded until it crashes under load; security investment only after a breach.
+
+## Diagnosis Process
+
+1. **Describe the problem neutrally** — symptoms, who/what is involved, what's been tried, what keeps recurring. No blame.
+2. **Sketch the loops** — what causes what; where reinforcing (amplifying) loops are, where balancing (limiting) loops are, and where the delays sit.
+3. **Match to an archetype** using the Quick Reference Card. If two fit, the system may be layered—note both.
+4. **Intervene at the structure, not the symptom** — use the Key Question to find the fundamental solution, the constraint to remove, or the missing/ delayed feedback to add. If none match, stop and use `thinking-systems`.
+
+## Verification Checklist
+
+- [ ] Problem described without blame
+- [ ] Loops sketched (reinforcing, balancing, delays)
+- [ ] Matched to a specific archetype (or escalated to `thinking-systems` because none fit)
+- [ ] Intervention targets structure, not the recurring symptom
+- [ ] Considered the side effects of the intervention
+
+## Senge's Wisdom
+
+"Structures of which we are unaware hold us prisoner. Once we can see them, they no longer have the same hold on us."
+
+The pattern continues until someone sees it and changes the structure driving it—not the behaviors, but what produces them.

package/config/skills/thinking-bayesian/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: thinking-bayesian
+description: Use when interpreting a test result, metric, or new evidence and you risk over-reacting to it. State the base rate first, then update belief by the likelihood ratio.
+---
+
+# Bayesian Reasoning
+
+## Overview
+Bayesian thinking provides a framework for updating beliefs based on new evidence. Rather than treating beliefs as binary (true/false), it recognizes degrees of confidence that should shift as evidence accumulates. This approach, rooted in Bayes' Theorem, helps avoid both overconfidence and underreaction to new information.
+
+**Core Principle:** State the base rate *before* you look at the evidence, then update. The single most common error is anchoring on a vivid result and skipping the prior — a positive test for a rare condition is usually still a false alarm.
+
+> **Redirect:** For nearly all uncertainty-reasoning tasks, prefer `thinking-probabilistic` — it covers forecasting with ranges, calibration, and uncertainty communication without requiring explicit priors and likelihood ratios. Reserve this skill for the narrow case where you have a specific, quantified prior AND a specific piece of evidence to combine via Bayes' rule. If you only need a rough updated number, the base-rate-then-likelihood-ratio trigger below is enough — don't run the full theorem.
+
+## Trigger Card
+
+When interpreting a test result, metric, or new evidence where overreaction is a risk:
+
+1. **State the base rate first** — what was the probability before the evidence?
+2. **Estimate the likelihood ratio** — how much more expected is the evidence under the hypothesis vs. not?
+3. **Update:** posterior odds = prior odds × likelihood ratio.
+
+If the base rate is very low (rare condition), a positive result is usually still a false alarm. Always start with the prior.
+
+## When to Use
+- Estimating probabilities or likelihoods
+- Interpreting test results or metrics
+- Making decisions with incomplete information
+- Evaluating competing hypotheses
+- Learning from experiments or A/B tests
+- Diagnosing problems with uncertain causes
+- Predicting outcomes based on historical data
+
+Decision flow:
+```
+Uncertain about something? → yes → Have prior belief? → yes → New evidence? → APPLY BAYESIAN UPDATE
+                                                      ↘ no → Establish base rate first
+                         ↘ no → Standard analysis may suffice
+```
+
+## When NOT to Use
+
+- **You're reasoning under uncertainty and don't have a specific prior + evidence pair.** Use `thinking-probabilistic` instead — it handles forecasting with ranges, calibration, and uncertainty communication without requiring formal Bayesian machinery.
+- **The evidence is conclusive or directly observable.** If you can read the logs, run the query, or look up the answer, do that — don't dress up a near-certainty as a probability.
+- **No meaningful prior exists** and you'd just be inventing numbers. A fabricated base rate gives false rigor; say the prior is unknown instead.
+- **The decision is the same at any plausible posterior.** If you'd act identically whether the probability is 40% or 70%, skip the update and act.
+- **You need to express uncertainty as a calibrated range**, not a point update from a single piece of evidence — that's `thinking-probabilistic` territory.
+
+## Key Concepts
+
+### Prior Probability
+Your belief BEFORE seeing new evidence:
+```
+P(H) = probability that hypothesis H is true
+
+Example: Before any symptoms, what's the probability someone has disease X?
+         Use base rate: If 1 in 1000 people have it, P(disease) = 0.001
+```
+
+### Likelihood
+How probable is the evidence IF the hypothesis is true?
+```
+P(E|H) = probability of seeing evidence E, given H is true
+
+Example: If someone HAS the disease, what's the probability of a positive test?
+         If test is 99% sensitive: P(positive|disease) = 0.99
+```
+
+### Posterior Probability
+Your belief AFTER seeing the evidence:
+```
+P(H|E) = updated probability of H, given you observed E
+
+This is what Bayes' Theorem calculates.
+```
+
+## Bayes' Theorem
+
+```
+                P(E|H) × P(H)
+P(H|E) = ─────────────────────────
+                   P(E)
+
+Where:
+  P(H|E) = posterior (what we want)
+  P(E|H) = likelihood (how expected is evidence if H true)
+  P(H)   = prior (initial belief)
+  P(E)   = total probability of evidence
+```
+
+### Intuitive Form
+
+```
+Posterior odds = Prior odds × Likelihood ratio
+
+If evidence is 10x more likely under H than under not-H,
+your odds should shift by factor of 10.
+```
+
+## The Process
+
+### Step 1: Establish Your Prior
+What did you believe before this evidence?
+- Use base rates when available
+- Be explicit about uncertainty
+- Don't anchor on 50% just because you're unsure
+
+```
+Question: Will this feature increase conversion?
+Prior: Based on similar features, ~30% succeed significantly
+       P(success) = 0.30
+```
+
+### Step 2: Assess the Evidence
+How strong is this evidence? Consider:
+- How likely is this evidence if hypothesis is TRUE?
+- How likely is this evidence if hypothesis is FALSE?
+- What's the ratio?
+
+```
+Evidence: Early A/B test shows 5% lift (p=0.08)
+P(this result | feature works) = 0.60 (moderately expected)
+P(this result | feature doesn't work) = 0.15 (possible but less likely)
+Likelihood ratio = 0.60 / 0.15 = 4x
+```
+
+### Step 3: Update Your Belief
+Apply the likelihood ratio to your prior:
+
+```
+Prior odds: 0.30 / 0.70 = 0.43
+Likelihood ratio: 4x
+Posterior odds: 0.43 × 4 = 1.72
+Posterior probability: 1.72 / (1 + 1.72) = 0.63
+
+Updated belief: 63% confidence feature will succeed
+(up from 30% prior)
+```
+
+### Step 4: Iterate as More Evidence Arrives
+Yesterday's posterior becomes today's prior:
+
+```
+New evidence: Week 2 shows lift holding at 4.5%
+Prior (from step 3): 0.63
+[Repeat update process]
+New posterior: 0.78
+```
+
+## Common Applications
+
+### Interpreting Test Results
+```
+Scenario: Test for rare disease (1 in 10,000 prevalence)
+Test: 99% sensitive, 99% specific
+
+Prior: P(disease) = 0.0001
+If positive test:
+  P(positive|disease) = 0.99
+  P(positive|no disease) = 0.01
+  P(positive) = 0.99 × 0.0001 + 0.01 × 0.9999 ≈ 0.0101
+
+Posterior: P(disease|positive) = (0.99 × 0.0001) / 0.0101 ≈ 0.0098
+
+Even with 99% accurate test, positive result only means ~1% chance of disease!
+Base rate dominates when condition is rare.
+```
+
+### Debugging
+```
+Bug report: Users see error X
+Prior beliefs:
+  P(database issue) = 0.20
+  P(network issue) = 0.30
+  P(code bug) = 0.40
+  P(user error) = 0.10
+
+Evidence: Error happens only on mobile
+  P(mobile-only | database) = 0.05
+  P(mobile-only | network) = 0.30
+  P(mobile-only | code bug) = 0.60
+  P(mobile-only | user error) = 0.40
+
+Update: Code bug becomes most likely (posterior ~0.55)
+Next step: Investigate mobile-specific code paths
+```
+
+### Project Estimation
+```
+Prior: Based on similar projects, P(on-time) = 0.40
+
+Evidence 1: Team is experienced with this stack
+  Likelihood ratio: 1.5x → Posterior: 0.50
+
+Evidence 2: Requirements are unclear
+  Likelihood ratio: 0.6x → Posterior: 0.38
+
+Evidence 3: Critical dependency has risk
+  Likelihood ratio: 0.7x → Posterior: 0.30
+
+Final estimate: 30% chance of on-time delivery
+```
+
+## Mental Shortcuts
+
+### Strong vs Weak Evidence
+| Evidence Type | Typical Likelihood Ratio |
+|---------------|-------------------------|
+| Definitive proof | 100x+ |
+| Strong evidence | 10-100x |
+| Moderate evidence | 3-10x |
+| Weak evidence | 1.5-3x |
+| Noise | ~1x (no update) |
+
+### When to Update Significantly
+Update strongly when:
+- Evidence is surprising under your current belief
+- Evidence comes from reliable source
+- Evidence is specific to your hypothesis
+
+Update weakly when:
+- Evidence is expected regardless of hypothesis
+- Source has unknown reliability
+- Evidence is circumstantial
+
+### Base Rate Neglect (Avoid This)
+Common error: Ignoring prior probability when evidence arrives
+```
+Wrong: "Positive test = probably have disease"
+Right: "Positive test shifts probability, but base rate matters"
+```
+
+## Calibration Check
+
+### Are You Well-Calibrated?
+Track predictions and outcomes:
+- Of things you said were "70% likely," did ~70% happen?
+- If you're always overconfident, widen your uncertainty
+- If you're always underconfident, trust your assessments more
+
+### Confidence Levels
+| Stated Confidence | Should Mean |
+|-------------------|------------|
+| 50% | Coin flip |
+| 70% | Would bet 2:1 |
+| 90% | Would bet 9:1 |
+| 99% | Would bet 99:1 |
+
+## Verification Checklist
+- [ ] Established explicit prior probability (not just "I think...")
+- [ ] Assessed likelihood ratio of evidence
+- [ ] Applied update mathematically (not just "more/less likely")
+- [ ] Considered base rates for rare events
+- [ ] Checked for base rate neglect
+- [ ] Documented reasoning for future calibration
+
+## Key Questions
+- "What was my belief before this evidence?"
+- "How likely is this evidence if my belief is true? If false?"
+- "What's the likelihood ratio?"
+- "Am I anchoring on the evidence and ignoring base rates?"
+- "How would I bet on this? At what odds?"
+
+## Kahneman's Warning
+"People tend to assess the relative importance of issues by the ease with which they are retrieved from memory—and this is largely determined by the extent of coverage in the media."
+
+Don't let vivid evidence override base rates. A plane crash doesn't make flying more dangerous than driving, even though it feels that way.