@polderlabs/bizar 10.7.0 → 10.7.2

package/.claude/skills/thinking-fermi-estimation/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: thinking-fermi-estimation
+description: Use when you need a number you can't measure and can't look up. Decompose the unknown into estimable factors and multiply for an order-of-magnitude answer. Don't Fermi a lookup-able value.
+---
+
+# Fermi Estimation
+
+## Overview
+
+Fermi estimation, named after physicist Enrico Fermi, is the art of making reasonable estimates for quantities that seem impossible to know without direct measurement. By decomposing a question into factors you can estimate, then multiplying, you often get surprisingly accurate order-of-magnitude results.
+
+**Core Principle:** Break the unknown into known (or estimable) pieces. Even rough estimates combine to reasonable accuracy due to errors canceling out.
+
+## Trigger Card
+
+When you need a number you can't measure or look up, and order-of-magnitude is enough:
+
+1. **Decompose:** Quantity = Factor₁ × Factor₂ × ... × Factorₙ (by component, by rate×time, or by population×fraction).
+2. **Estimate each factor** with a range, not a point; use geometric mean for order-of-magnitude; round to one significant figure.
+3. **Multiply and sanity-check:** Does the order of magnitude make sense? Would a 10× error change the decision?
+4. **Report:** "~X, within 3-5×" — never false precision.
+
+If the number is lookup-able (COUNT(*), pricing page, profile it), do that instead — a made-up estimate where a real value exists is strictly worse.
+
+## When to Use
+
+- Capacity planning ("How much storage will we need?")
+- Cost estimation ("What will this infrastructure cost?")
+- Market sizing ("How many potential users exist?")
+- Feasibility assessment ("Is this even plausible?")
+- Sanity checking ("Does this number make sense?")
+- Interview questions ("How many piano tuners in Chicago?")
+- Quick prioritization ("Is this worth pursuing?")
+
+Decision flow:
+
+```
+Need a number you don't have? → Can you measure OR look it up cheaply? → yes → DO THAT (don't Fermi it)
+                                                                       ↘ no → Will an order-of-magnitude answer suffice? → yes → FERMI ESTIMATE
+                                                                                                                          ↘ no → you need real data, go get it
+```
+
+## When NOT to Use
+
+- **The number is cheaply lookup-able or measurable.** Don't Fermi the size of a table you can `COUNT(*)`, the latency you can profile, the file size you can `ls`, the price on a pricing page, or any fact one query/search away. A made-up estimate where a real value is available is strictly worse — it adds error and false confidence. Look it up.
+- **You need precision, not order of magnitude.** Fermi gives you "~4 TB, within 3-5x." If the decision turns on 3.8 vs 4.2, estimation can't carry it — get the real number.
+- **The factors are correlated or you'd be inventing the base rates.** If the decomposition is just stacked guesses with no anchor, the result is theater. Either find one real anchor or flag the whole thing as a rough guess.
+- **The decision is identical across the plausible range.** If "somewhere between 1 GB and 1 TB" doesn't change what you do, skip the estimate and act.
+
+## The Fermi Process
+
+### Step 1: Clarify What You're Estimating
+
+Be precise about the quantity:
+
+```
+Vague: "How big is the market?"
+Precise: "How many SaaS companies with 50-500 employees in the US
+         would pay $1000/month for our product?"
+```
+
+### Step 2: Decompose into Estimable Factors
+
+Break into pieces you can estimate:
+
+```
+Storage needs for user data:
+= (Number of users)
+  × (Data per user per day)
+  × (Days of retention)
+  × (Overhead factor)
+```
+
+**Decomposition strategies:**
+
+| Strategy | Example |
+|----------|---------|
+| By component | Total = Sum of parts |
+| By rate × time | Total = Rate × Duration |
+| By population × fraction | Target = Base × Percentage |
+| By analogy × adjustment | New ≈ Similar × Ratio |
+
+### Step 3: Estimate Each Factor
+
+For each factor, estimate based on:
+
+| Source | Example |
+|--------|---------|
+| Known data | "We have 10,000 DAU" |
+| Industry benchmarks | "Average SaaS churn is 5%" |
+| Physical constraints | "A human can make ~50 decisions/day" |
+| Logical bounds | "At least 1, at most 1 million" |
+| Personal experience | "I've seen systems handle 1000 req/s" |
+
+**When estimating:**
+- Use ranges, not point estimates: "10,000 to 50,000"
+- Prefer geometric mean for order-of-magnitude: √(10,000 × 50,000) = 22,360
+- Round to one significant figure: ~20,000
+
+### Step 4: Combine Factors
+
+Multiply (or add) factors together:
+
+```
+Storage = 50,000 users × 10 KB/user/day × 365 days × 1.5 overhead
+        = 50,000 × 10,000 × 365 × 1.5 bytes
+        = 274 billion bytes
+        ≈ 270 GB/year
+```
+
+### Step 5: Sanity Check
+
+Verify reasonableness:
+- Does the order of magnitude make sense?
+- Is it physically possible?
+- Does it match any known data points?
+- Would a 10x error change the decision?
+- **Is any factor actually lookup-able?** If so, replace the estimate with the real value — every measured factor you substitute shrinks the error bars.
+
+### Step 6: State Confidence and Implications
+
+```
+Estimate: ~270 GB/year
+Confidence: Within 3-5x (80-1,500 GB)
+Implication: Standard database tier sufficient; no special infrastructure needed
+```
+
+## Fermi Estimation Template
+
+```markdown
+# Fermi Estimate: [Question]
+
+## Question (Precise)
+[Exactly what we're estimating]
+
+## Decomposition
+[Quantity] = [Factor 1] × [Factor 2] × ... × [Factor N]
+
+## Factor Estimates
+
+### Factor 1: [Name]
+- Estimate: [Value]
+- Source/Reasoning: [Why this number]
+- Confidence: High / Medium / Low
+
+### Factor 2: [Name]
+- Estimate: [Value]
+- Source/Reasoning: [Why this number]
+- Confidence: High / Medium / Low
+
+[Continue for all factors...]
+
+## Calculation
+[Show the math]
+
+## Result
+- Point estimate: [Value]
+- Range: [Low] to [High] (representing Xx uncertainty)
+
+## Sanity Check
+- Physical plausibility: [Check]
+- Comparison to known data: [Check]
+- Order of magnitude reasonable: [Check]
+
+## Implications
+[What does this estimate mean for the decision?]
+```
+
+## Common Decomposition Patterns
+
+### Capacity Planning
+```
+Needed = Users × Usage/User × Factor/Usage × Growth × Safety
+```
+
+### Cost Estimation
+```
+Cost = Resources × Unit Cost × Duration × Overhead
+```
+
+### Time Estimation
+```
+Time = Tasks × Time/Task × (1 + Risk Factor)
+```
+
+### Market Sizing
+```
+Market = Population × Segment% × Adoption% × Price × Frequency
+```
+
+## Tips for Better Estimates
+
+### Use Multiple Approaches
+
+Estimate the same thing different ways:
+
+```
+Website traffic estimate:
+Method 1: Bottom-up from user base
+Method 2: Top-down from market share
+Method 3: Analogy to similar company
+
+If methods agree within 3x, confidence increases
+If they diverge wildly, investigate assumptions
+```
+
+### Bound First
+
+Start with upper and lower bounds:
+
+```
+"Definitely more than 1,000, definitely less than 10 million"
+"So somewhere in 10,000-1,000,000 range"
+"Let me narrow from there..."
+```
+
+### Watch for Correlated Errors
+
+If factors are correlated, errors don't cancel:
+
+```
+BAD: Users × Revenue/User (both depend on same growth assumption)
+BETTER: Estimate revenue directly, or use independent factors
+```
+
+### One Significant Figure
+
+Don't false precision:
+
+```
+Calculation: 47,832,519 bytes
+Report: ~50 MB (not "47.8 MB")
+```
+
+## Verification Checklist
+
+- [ ] Question stated precisely
+- [ ] Decomposed into 3-6 estimable factors
+- [ ] Each factor has reasoning/source
+- [ ] Factors are relatively independent
+- [ ] Calculation shown and checked
+- [ ] Result sanity-checked against reality
+- [ ] Uncertainty range stated
+- [ ] Implications for decision clarified
+
+## Key Questions
+
+- "Can I break this into smaller, estimable pieces?"
+- "What do I already know that constrains this?"
+- "What's the upper bound? Lower bound?"
+- "Does this number pass the smell test?"
+- "Would being off by 10x change my decision?"
+- "Can I estimate this a different way to cross-check?"
+
+## Fermi's Wisdom
+
+When asked how many piano tuners were in Chicago, Fermi didn't look it up—he estimated from population, households, pianos, tuning frequency, and tuner capacity. His estimate was reportedly within 20% of the actual number.
+
+The lesson: You know more than you think. Decompose, estimate, combine. The errors often cancel, and you get surprisingly close to truth.
+
+"Never make a calculation until you know the answer." — John Wheeler (Fermi's colleague)
+
+Meaning: Estimate first to know what answer to expect, then calculate to verify.

package/.claude/skills/thinking-first-principles/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: thinking-first-principles
+description: When a constraint is treated as fixed ("too expensive", "impossible", "always done this way"), ask whether it's physics or just convention, then rebuild from what's actually true.
+---
+
+# First Principles Reasoning
+
+## Overview
+First principles thinking strips away assumptions and conventions to reveal fundamental truths, then reconstructs solutions from those basics. This approach, championed by Elon Musk and rooted in Aristotle's philosophy, enables breakthrough solutions by escaping the trap of reasoning by analogy.
+
+**Core Principle:** Don't accept "that's how it's always done." Reduce to fundamentals, then rebuild.
+
+## When to Use
+- Conventional approaches have failed or seem inadequate
+- You're told something is "impossible" or "too expensive"
+- Designing new systems/products from scratch
+- Challenging industry assumptions or pricing
+- Problem seems intractable using existing mental models
+- You need innovation rather than incremental improvement
+
+Decision flow:
+```
+Problem intractable? → yes → Are you reasoning from analogy? → yes → APPLY FIRST PRINCIPLES
+                                                            ↘ no → Already at fundamentals
+                  ↘ no → Standard problem-solving may suffice
+```
+
+## When NOT to Use
+- The constraint is genuinely physics/cost/regulation, not convention — verify, then accept it and move on.
+- A well-trodden, working solution already exists; reinventing from scratch adds risk without lift. Use the convention.
+- Routine implementation where the "why" is settled — don't re-derive a standard library, protocol, or known-good pattern.
+- Time-critical incidents: act on the most likely cause first (occams-razor), reserve first-principles for the post-incident redesign.
+
+## Trigger Card
+
+When a constraint is treated as fixed ("too expensive", "impossible", "always done this way"):
+
+1. **Ask: is this constraint physics or convention?** If it's a law of nature, accept it. If it's "how we've always done it," it's negotiable.
+2. **Identify the irreducible truths** — what must be true no matter what solution you pick?
+3. **Rebuild from those truths** — derive a solution that satisfies the real constraints but ignores the artificial ones. If a simpler rebuild solves it, stop.
+
+Skip if the "why" is settled (standard library, known-good pattern). In an incident, act on the most likely cause first; reserve this for post-incident redesign.
+
+## The Process
+
+### Step 1: Identify Current Assumptions
+List everything you "know" or assume about the problem:
+- What are the constraints everyone accepts?
+- What costs/limitations are considered fixed?
+- What's the conventional wisdom?
+- Why do people say it can't be done?
+
+```
+Example: "Rocket launches cost $65M because that's what aerospace companies charge"
+Assumptions: Must buy from existing suppliers, existing designs are optimal, 
+             materials must be aerospace-grade, vertical integration is too hard
+```
+
+### Step 2: Break Down to Fundamentals
+Ask repeatedly: "What are we absolutely certain is true?"
+
+Decomposition questions:
+- What are the physical/mathematical constraints?
+- What are the raw inputs required?
+- What laws of physics/economics apply?
+- What would this cost if built from raw materials?
+- What is the minimum viable version?
+
+```
+Example: Rocket raw materials (aluminum, titanium, copper, carbon fiber)
+         = ~2% of typical rocket price
+Fundamental truth: Materials aren't the cost driver; 
+                   manufacturing/overhead/margins are
+```
+
+### Step 3: Challenge Each Assumption
+For each assumption, ask:
+- Is this actually true, or just convention?
+- What evidence supports this?
+- Under what conditions would this be false?
+- Who benefits from this assumption persisting?
+
+Use the "5 Whys" to drill deeper:
+```
+Why is it expensive? → Suppliers charge high margins
+Why? → Limited competition
+Why? → High barriers to entry
+Why? → Assumption that you must use existing supply chain
+Why? → Nobody questioned it
+```
+
+### Step 4: Rebuild from Fundamentals
+Starting ONLY from verified truths:
+- What's the simplest solution that satisfies fundamental requirements?
+- What new approaches become possible without false constraints?
+- How would you solve this if starting from scratch today?
+- What would a solution look like with 10x less resources?
+
+```
+Example: Build rockets in-house using commodity materials
+         = SpaceX reduced launch costs by 10x
+```
+
+### Step 5: Validate Against Reality
+- Does your reconstructed solution violate any physics/laws?
+- What practical constraints remain?
+- What's the minimum viable test?
+- How can you prove/disprove this quickly?
+
+## Mental Traps to Avoid
+
+| Trap | Description | Antidote |
+|------|-------------|----------|
+| Reasoning by Analogy | "Others do it this way" | Ask "but is it optimal?" |
+| Appeal to Authority | "Experts say it's impossible" | "What specifically makes it impossible?" |
+| Sunk Cost | "We've always done it this way" | "What if we started fresh today?" |
+| Complexity Bias | Assuming complex = better | "What's the simplest version?" |
+| False Constraints | Accepting artificial limits | "Is this a law of physics or convention?" |
+
+## Application Examples
+
+### Software Architecture
+```
+Assumption: "We need a microservices architecture"
+First Principles:
+- What problem are we solving? (scalability, team independence, deployment)
+- What's the minimum that achieves this?
+- A modular monolith might suffice for current scale
+```
+
+### Cost Reduction
+```
+Assumption: "This service costs $50k/month, that's just cloud pricing"
+First Principles:
+- What compute/storage do we actually need?
+- What are we paying for that we don't use?
+- Could we reduce by 80% with right-sizing?
+```
+
+### Feature Development
+```
+Assumption: "Users need feature X (because competitor has it)"
+First Principles:
+- What job is the user trying to accomplish?
+- What's the simplest way to enable that job?
+- Maybe a different approach solves it better
+```
+
+## Verification Checklist
+- [ ] Listed all assumptions about the problem
+- [ ] Identified which assumptions are physics/math vs convention
+- [ ] Challenged at least 3 "obvious" constraints
+- [ ] Rebuilt solution using only verified fundamentals
+- [ ] Validated that solution doesn't violate actual constraints
+- [ ] Identified minimum viable test to prove/disprove approach
+
+## Combining with Other Models
+- **Inversion**: After first principles, ask "what would make this fail?"
+- **Second-Order Thinking**: Consider downstream effects of your new approach
+- **Pre-Mortem**: Imagine your first-principles solution failed—why?
+
+## Key Questions
+- "What do we know to be absolutely true?"
+- "Why does everyone assume this constraint exists?"
+- "What would we do if we had to solve this with 10% of the budget?"
+- "If we were starting from scratch today, would we build it this way?"
+- "What would a complete outsider try?"

package/.claude/skills/thinking-five-whys-plus/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: thinking-five-whys-plus
+description: Use when a fault is localized to a component and the proximate cause is known but the systemic root is not — chain 'why' with evidence, a counterfactual cause test, and an explicit stop condition.
+---
+
+# Five Whys Plus
+
+## Overview
+
+Five Whys Plus is a **post-localization root-cause analysis** skill. It assumes a fault has already been localized to a specific component or subsystem (by `thinking-scientific-method` or equivalent hypothesis-differential debugging). From that starting point — the proximate cause is known — it chains "why" questions backward to reach the systemic root cause, with explicit guards against the technique's known failure modes.
+
+**Core Principle:** Never ask "why" without evidence for the answer. Chain backward from localized fault to actionable root cause, and stop only when the cause passes a counterfactual test: "Would the problem NOT have occurred if this cause were absent?"
+
+## When to Use
+
+- A fault has been localized to a specific component (use `thinking-scientific-method` first if you don't know which component is at fault)
+- The proximate cause is known but the systemic cause isn't
+- A problem keeps recurring despite previous fixes
+- You need the root cause, not just the proximate one
+
+Decision flow:
+
+```
+Fault localized to a specific component?
+  → No → Run thinking-scientific-method first to localize
+  → Yes → Proximate cause known?
+      → No → Gather evidence on proximate cause
+      → Yes → Is the root cause already obvious and verified?
+          → Yes → Fix directly; don't chain
+          → No → APPLY FIVE WHYS PLUS
+```
+
+## When NOT to Use
+
+- **The fault is not yet localized.** If you don't know which component is at fault (multiple candidate causes), this is a localization problem. Use `thinking-scientific-method` (hypothesis-differential debugging) first, then run Five Whys on the cause it confirms.
+- **The root cause is already obvious and verified.** Don't ritualistically chain "why" — just fix it.
+- **The chain would be pure speculation with no evidence for the next "why".** Stop and gather evidence; don't speculate deeper (see Anti-Patterns: Speculation Dive).
+- **The problem is a one-off with no systemic dimension.** If a single fat-finger error caused an outage and there's no process gap, don't force a chain.
+
+## Procedure
+
+### Step 1: State the Problem Precisely
+
+Document the localized fault with specific, measurable details:
+
+```markdown
+Problem Statement:
+- What happened: [Specific observable symptom]
+- Localized to: [Component/subsystem confirmed by scientific-method or equivalent]
+- When: [Time range]
+- Where: [Affected systems/users]
+- Extent: [Scope and severity]
+- Impact: [Business/user impact]
+```
+
+### Step 2: Build the Evidence Chain
+
+For each "why," require evidence, confidence, and alternatives considered:
+
+```markdown
+Why #N: Why did [answer N-1] occur?
+Answer: [Hypothesis]
+Evidence: [Data, logs, metrics that support this — NOT speculation]
+Confidence: High / Medium / Low
+What else considered: [Alternative causes checked]
+Ruled out because: [Evidence against alternatives]
+```
+
+**Evidence types:** Logs showing the event, metrics correlating with timeline, code showing the behavior, configuration proving the state, testimony from multiple independent sources.
+
+**Branch on "what else?"** at each step — explicitly list and rule out alternative explanations before proceeding.
+
+### Step 3: Apply the Counterfactual Cause Test
+
+Before stopping, test the proposed root cause:
+
+> **Counterfactual:** "Would the problem NOT have occurred if this cause were absent?"
+
+If the answer is "no" or "maybe not" — you haven't reached the root cause. Keep going.
+
+If the answer is "yes, the problem would not have occurred" — AND the cause passes the stop condition (Step 4) — you've found the root cause.
+
+### Step 4: Check the Stop Condition
+
+Only stop when ALL criteria are met:
+
+| Criterion | Question |
+|-----------|----------|
+| Actionable | Can we take concrete action on this cause? |
+| Controllable | Is this within our control to fix? |
+| Fundamental | Would fixing this prevent recurrence? |
+| Evidenced | Do we have evidence, not just speculation? |
+| Counterfactual | Would the problem NOT have occurred if this cause were absent? |
+| Not-blame | Is this a system/process issue, not just "someone messed up"? |
+
+**Never stop at human error.** When you reach "someone made a mistake," ask "Why was the mistake possible?" — that's the systemic cause.
+
+### Step 5: Apply Devil's Advocate Review
+
+Before finalizing, challenge the conclusion:
+
+```markdown
+Counter-analysis:
+1. What evidence contradicts this conclusion?
+2. What other explanation fits the evidence equally well?
+3. Would someone outside our team reach the same conclusion?
+4. If we fix X, are we confident the problem won't recur?
+5. Are we finding what we expected to find? (confirmation bias check)
+```
+
+### Step 6: Document and Recommend
+
+Record the full chain and prescribe actions that address the root cause (not just the symptom).
+
+## Output Contract
+
+A completed Five Whys Plus analysis produces:
+
+1. **Problem Statement** — specific, measurable, with localized component
+2. **Evidence Chain** — each "why" step with answer, evidence, confidence, and alternatives ruled out
+3. **Counterfactual Test Result** — explicit answer to "would the problem NOT have occurred?"
+4. **Stop Condition Check** — all six criteria satisfied
+5. **Devil's Advocate Review** — contradicting evidence, alternative explanations, bias check
+6. **Root Cause(s)** — primary and any contributing factors
+7. **Recommended Actions** — addressing root cause, with owner and timeline
+8. **Verification Plan** — how to confirm the fix worked
+
+## Anti-Patterns
+
+| Anti-Pattern | Symptom | Correction |
+|---|---|---|
+| **Pre-localization application** | Running Five Whys when you don't know which component failed | Use `thinking-scientific-method` first to localize |
+| **Premature stop** | Accepting the first plausible cause without the counterfactual test | Apply the counterfactual: "Would the problem NOT have occurred?" |
+| **Blame stop** | Ending at "someone made a mistake" | Ask "Why was the mistake possible?" — find the systemic gap |
+| **Speculation dive** | Answers become increasingly speculative without evidence | Stop and gather evidence; mark un-evidenced steps as hypotheses |
+| **Circular why** | "Why A?" → "Because B" → "Why B?" → "Because A" | Introduce external evidence or a third factor to break the cycle |
+| **Single-cause bias** | Assuming one root cause without branching | At each step, ask "what else could cause this?" and rule out alternatives |
+| **Confirmation bias** | Finding the cause you expected to find | Devil's advocate review; ask "what evidence contradicts this?" |
+| **Ritualistic chaining** | Asking five whys when one would do | Stop when the counterfactual test passes and the stop condition is met |