@polderlabs/bizar 10.7.1 → 10.7.2

package/.claude/skills/thinking-occams-razor/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: thinking-occams-razor
+description: Use when multiple causes could explain a bug — test the fewest-assumption hypothesis first; escalate to complex only when evidence forces it. Skip the full procedure when one step resolves it.
+---
+
+# Occam's Razor
+
+## Overview
+
+Occam's Razor states: among competing hypotheses that fit the evidence equally well, prefer the one with the fewest assumptions. This skill operationalizes that principle for debugging: **test the simplest hypothesis first, and escalate to complex explanations only when evidence forces it.**
+
+The skill has a **trigger-shrink gate**: if the simplest hypothesis can be tested in one step, just test it — don't run the full enumeration-and-scoring procedure. Reserve the full procedure for situations where multiple hypotheses genuinely compete and the simplest is not obviously testable.
+
+**Core Principle:** "Everything should be made as simple as possible, but no simpler." — Einstein
+
+## When to Use
+
+- Multiple hypotheses could explain a bug and the simplest is NOT obviously testable in one step
+- You're about to investigate a complex hypothesis without first testing a simpler one
+- Architecture or design decisions where several approaches are viable and differ in complexity
+- Root cause analysis where several causes seem plausible
+
+Decision flow:
+
+```
+Multiple explanations exist?
+  → No → Use the available explanation
+  → Yes → Can the simplest be tested in one step?
+      → Yes → JUST TEST IT (trigger-shrink — skip full procedure)
+      → No → Do they explain the evidence equally well?
+          → No → Prefer the better explanation
+          → Yes → RUN FULL OCCAM'S RAZOR PROCEDURE
+```
+
+## When NOT to Use
+
+- **Evidence already points to a specific cause.** Follow the evidence; don't downgrade to a "simpler" hypothesis it contradicts.
+- **The domain is irreducibly complex** (distributed consensus, concurrency, security threat models). The simplest model is wrong; don't oversimplify ("but no simpler").
+- **Only one plausible explanation exists.** There's nothing to compare — just test it.
+- **"Simple" would mean ignoring a known interaction or skipping a load-bearing safeguard.** Local simplicity that creates systemic risk isn't parsimony.
+- **The trigger check resolves it.** If you can test the simplest hypothesis in one step and it's confirmed, you're done — don't enumerate for completeness.
+
+## Trigger Card
+
+Before running the full enumeration-and-scoring procedure, ask one question: **"Can I test the simplest hypothesis in one step?"**
+
+1. **Identify the simplest hypothesis** — the one with the fewest assumptions that still explains the evidence.
+2. **Can you test it in one step?** → Yes → **Just test it.** If confirmed, report and stop. If refuted, move to the next simplest.
+3. **If it can't be tested in one step** → run the full Occam's Razor procedure (enumerate, count assumptions, verify explanatory power, test in order).
+
+If evidence already points to a specific cause, follow the evidence — don't downgrade to a "simpler" hypothesis it contradicts. For irreducibly complex domains (distributed consensus, concurrency), the simplest model is wrong.
+
+## Procedure
+
+### Trigger Check (Fast Path)
+
+Before running the full procedure, ask: **"Can I test the simplest hypothesis in one step?"**
+
+- Yes → Test it. If confirmed, report and stop. If falsified, move to the next simplest.
+- No → The simplest hypothesis requires non-trivial investigation → run the full procedure below.
+
+### Full Procedure: When the Trigger Check Doesn't Resolve
+
+#### Step 1: Enumerate Competing Hypotheses
+
+List all plausible explanations for the observed behavior:
+
+```
+Bug: Users intermittently can't log in
+
+Hypotheses:
+A. Session token expiration edge case
+B. Race condition in auth service
+C. Database connection pool exhaustion
+D. Complex interaction between CDN cache, load balancer, and session service
+```
+
+#### Step 2: Count Assumptions per Hypothesis
+
+| Hypothesis | Assumptions |
+|------------|-------------|
+| A. Token expiration | 1. Token validation has an edge case |
+| B. Race condition | 1. Concurrent requests possible, 2. Shared mutable state exists |
+| C. DB pool exhaustion | 1. Pool is undersized, 2. Connections are leaking |
+| D. Complex interaction | 1. CDN caches auth, 2. LB sticky sessions fail, 3. Session sync delayed |
+
+Count each independent assumption: +1 per assumption, +1 per component involved, +2 per external dependency, +2 for timing-dependent behavior, +3 for rare conditions, +5 for "perfect storm" scenarios.
+
+#### Step 3: Verify Explanatory Power
+
+Ensure simpler hypotheses actually explain the evidence:
+
+```
+Evidence: Failures correlate with high traffic periods
+Hypothesis A (token edge case): Doesn't explain traffic correlation ✗
+Hypothesis C (DB pool exhaustion): Explains traffic correlation ✓ — fewer assumptions than D
+→ PREFERRED by Occam's Razor
+```
+
+#### Step 4: Test in Order of Fewest Assumptions
+
+Investigate hypotheses from fewest to most assumptions. Do not skip to complex hypotheses until simple ones are ruled out.
+
+#### Step 5: Escalate Complexity Only When Evidence Forces It
+
+When simple explanations are ruled out with evidence, move to more complex ones. Never escalate on intuition alone.
+
+## Output Contract
+
+A completed Occam's Razor analysis produces:
+
+1. **Trigger Check Result** — whether the simplest hypothesis was testable in one step
+2. **Hypothesis Ranking** — ordered by assumption count, with each hypothesis' assumptions listed
+3. **Explanatory Power Check** — which hypotheses fit the evidence
+4. **Test Order and Results** — which hypotheses were tested, in what order, and the outcome
+5. **Conclusion** — the confirmed hypothesis (or the next to test if unresolved)
+
+For trigger-shrink cases, the output may be a single line: "Tested simplest hypothesis X — confirmed/refuted."
+
+## Anti-Patterns
+
+| Anti-Pattern | Symptom | Correction |
+|---|---|---|
+| **Oversimplifying irreducible domains** | Applying "simplest" to distributed consensus or security models | "But no simpler" — respect domain complexity |
+| **Complexity bias** | Assuming complex = sophisticated, testing complex hypotheses first | Test fewest-assumption hypotheses first, always |
+| **Trigger inflation** | Running the full enumeration for a one-step test | If the simplest is one-step testable, just test it |
+| **Ignoring explanatory power** | Choosing the simplest hypothesis that doesn't fit the evidence | Fewer assumptions doesn't beat not fitting the data |
+| **Local simplicity, systemic risk** | Choosing a simple local fix that creates fragility elsewhere | Prefer systemic simplicity over local simplicity |
+| **Ritualistic assumption counting** | Spending more time counting assumptions than testing | The point is prioritization, not precision; rough count is enough |

package/.claude/skills/thinking-ooda/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: thinking-ooda
+description: Use under time pressure (incident, outage, debugging a moving target) when you must act before you have certainty—cycle Observe→Orient→Decide→Act on ~70% confidence, then re-observe.
+---
+
+# OODA Loop
+
+## Overview
+The OODA Loop (Observe, Orient, Decide, Act) is a framework for acting in fast-moving, uncertain situations. The core decision rule: don't wait for certainty—act on the best current understanding, then immediately observe the result and loop again. Speed through the loop beats a perfect plan that arrives too late.
+
+**Core Principle:** Act on ~70% confidence for reversible moves, then re-observe. Cycle faster than the situation changes.
+
+## When to Use
+- Incident response and outages
+- Debugging a moving target (intermittent failure, ongoing degradation)
+- Any time-sensitive decision where the situation is still changing
+
+```
+Situation changing rapidly AND need to act before certainty? → yes → APPLY OODA
+                                                              → no  → use deliberate analysis / a hypothesis differential
+```
+
+## When NOT to Use
+- The situation is static and you have time → deliberate analysis beats fast looping.
+- The action is irreversible/high-blast-radius → gather more information before acting; 70% confidence isn't enough.
+- You can cheaply and directly localize the cause (read the diff/log) → use `thinking-scientific-method` (hypothesis differential) instead of looping in the dark.
+
+## Trigger Card
+
+When under time pressure (incident, outage, debugging a moving target) and you must act before certainty:
+
+1. **Observe** — what is happening right now? Gather the cheapest, highest-signal data available.
+2. **Orient** — what does it mean given your mental model? Update the model if the data contradicts it.
+3. **Decide** — pick an action on ~70% confidence. Don't wait for 100%.
+4. **Act** — execute, then immediately re-observe. The loop is the point; speed beats precision.
+
+If the action is irreversible or high-blast-radius, gather more information before acting. If you can cheaply localize the cause (read the diff/log), use `thinking-scientific-method` instead.
+
+## The Four Phases
+
+### 1. OBSERVE — gather current state fast
+- Current metrics, logs, alerts, error rates
+- What changed recently (deploys, config, traffic)
+- Feedback from your last action
+- Cast wide, then narrow as a pattern emerges. Time-box it—don't observe forever.
+
+```
+Incident: error rate 10x normal; affects API gateway + user service;
+started 5 min ago; a deploy went out 15 min ago; users report login failures.
+```
+
+### 2. ORIENT — make sense of it (the critical phase)
+Match the observations to a pattern and form a hypothesis. This is where most loops go wrong: don't lock onto the first framing. Hold ≥2 candidate explanations and let new evidence shift you.
+
+```
+Pattern resembles last month's connection-pool exhaustion, BUT no DB anomaly this time.
+The deploy touched auth rate-limiting.
+Hypothesis: rate-limit config is too aggressive.
+```
+
+### 3. DECIDE — pick an action under uncertainty
+- State the action and the hypothesis it tests.
+- 70% confidence now beats 90% too late, for a reversible action.
+- Decide what you'll observe next to confirm or refute.
+
+```
+Decision: roll back the auth deploy.
+Hypothesis: this restores normal error rates.
+Will watch: error rate for 2 minutes; fallback = investigate DB connections.
+```
+
+### 4. ACT — execute, then immediately re-observe
+Execute decisively and go straight back to OBSERVE. The action creates new information; don't wait blindly for it to "settle."
+
+```
+Action: roll back deployment/auth-service.
+Immediate observe: error rate, response times, 2-minute window.
+```
+
+The loop restarts until the system is stable.
+
+## What Speeds the Loop
+| Speeds it up | Stalls it |
+|--------------|-----------|
+| Pre-planned responses for known scenarios | Waiting for certainty (stuck at Observe/Decide) |
+| Good observability (fast, trustworthy signals) | Information overload (Observe never ends) |
+| Clear hypotheses (fast Orient) | Locking onto one hypothesis (Orient lock) |
+| Reversible actions you can undo | Seeking the perfect fix (Decide never ends) |
+
+## Application Patterns
+
+### Incident Response
+```
+OBSERVE: metrics, logs, alerts, recent changes
+ORIENT:  match pattern, form ≥2 hypotheses, assess blast radius
+DECIDE:  mitigation (rollback, scale, disable feature)
+ACT:     execute, immediately observe results
+LOOP:    continue until stable
+```
+
+### Debugging Under Pressure
+```
+OBSERVE: errors, stack traces, recent changes
+ORIENT:  form a hypothesis about the cause
+DECIDE:  test the most likely hypothesis first
+ACT:     add logging / try the fix / eliminate the possibility
+LOOP:    update the hypothesis from the result
+```
+
+## Common Failure Modes
+| Failure | Symptom | Fix |
+|---------|---------|-----|
+| Observation overload | Can't process all data | Filter to key indicators |
+| Orientation lock | Stuck on one hypothesis | Force a second framing |
+| Decision paralysis | Waiting for certainty | Set a decision deadline; act on 70% |
+| Action without observation | Blind execution | Mandate observe-after-act |
+| Not actually looping | Stuck in one phase | Time-box each phase |
+
+## Key Questions
+- "What do I observe RIGHT NOW?" (not 5 minutes ago)
+- "What pattern does this match—and what's my second hypothesis?"
+- "What's my best reversible action given current understanding?"
+- "How will I know in the next 2 minutes whether it worked?"
+- "Am I cycling, or stuck in one phase?"
+
+## Boyd's Insight
+"He who can handle the quickest rate of change survives." The goal isn't just making decisions—it's making and revising them faster than the situation compounds. Speed creates options; delay eliminates them.

package/.claude/skills/thinking-opportunity-cost/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: thinking-opportunity-cost
+description: Before committing scarce time/people/money to one thing, ask "what's the next-best use of these resources, and what does doing nothing cost?" — the real cost is the best option you skip.
+---
+
+# Opportunity Cost Thinking
+
+## Two operative prompts (use these first)
+1. **Next-best alternative:** "If we didn't do this, what is the single best thing we'd do with the same resources instead?" That foregone option *is* the cost.
+2. **Explicit do-nothing:** "What happens if we change nothing?" Always put status quo on the list — it's often undervalued and sometimes wins.
+
+If both answers are cheap/obvious, you don't need the full framework below — just decide.
+
+## Overview
+
+Opportunity cost is the value of the next-best alternative foregone when making a choice. Every decision to do X is simultaneously a decision not to do Y, Z, and everything else. Engineers often focus on the value of their chosen path while underweighting what they're giving up.
+
+**Core Principle:** The true cost of anything is what you give up to get it. A "free" option that consumes time has massive opportunity cost.
+
+## When to Use
+
+- Resource allocation (time, money, people)
+- Feature prioritization
+- Build vs. buy decisions
+- Technical debt evaluation
+- Career decisions
+- Architecture choices
+- Saying "yes" to any commitment
+
+Decision flow:
+
+```
+Making a commitment?
+  → Have you considered what you're NOT doing? → no → APPLY OPPORTUNITY COST
+  → Is the foregone value significant? → yes → Factor into decision
+                                       ↘ no → Proceed
+```
+
+## When NOT to Use
+- The choice is trivial or reversible and consumes negligible resources — deciding costs less than analyzing.
+- There is no real alternative use for the resource (it's idle or earmarked) — no opportunity is being given up.
+- The work is mandatory (compliance, security fix, hard dependency) — there's no optional alternative to weigh.
+- You'd be inventing speculative alternatives to look rigorous — if the next-best option is clearly worse, just proceed.
+
+## Trigger Card
+
+Before committing scarce time, people, or money to one thing:
+
+1. **Name the next-best alternative** — what would these resources do if not used here? Be specific.
+2. **Compare value** — what does the primary option deliver vs. the next-best? The real cost is what you give up.
+3. **Ask: "what does doing nothing cost?"** — sometimes the cheapest option is to wait. If delaying is free, consider it.
+
+Skip if the work is mandatory (compliance, security fix, hard dependency) — there's no optional alternative. If the next-best option is clearly worse, don't manufacture alternatives to look rigorous.
+
+## The Opportunity Cost Framework
+
+### Step 1: Identify the Choice
+
+State the decision explicitly:
+
+```
+Choice: Build custom authentication system
+Commitment: 3 engineers for 4 months
+```
+
+### Step 2: List the Alternatives
+
+What else could you do with those resources?
+
+```
+Alternatives for 3 engineers × 4 months:
+A. Build custom auth (the choice)
+B. Use Auth0 ($500/mo) + build 3 features
+C. Improve performance of existing system
+D. Reduce technical debt backlog by 40%
+E. Build new product line MVP
+```
+
+### Step 3: Value Each Alternative
+
+Estimate the value of each path:
+
+```markdown
+| Alternative | Direct Value | Strategic Value | Risk | Total Value |
+|-------------|--------------|-----------------|------|-------------|
+| Custom auth | Full control, no vendor cost | IP ownership | High (security) | Medium |
+| Auth0 + features | Features faster | Time to market | Low | High |
+| Performance work | 2x throughput | Customer satisfaction | Low | Medium-High |
+| Tech debt | Faster future dev | Developer retention | Low | Medium |
+| New product MVP | Revenue diversification | Growth potential | High | High |
+```
+
+### Step 4: Calculate Opportunity Cost
+
+Opportunity cost = Value of best foregone alternative
+
+```
+If we choose Custom Auth:
+  Best alternative foregone: Auth0 + features (rated "High")
+  Opportunity cost: The features we won't build + faster time to market
+```
+
+### Step 5: Make Decision with Full Accounting
+
+Total cost of choice = Direct cost + Opportunity cost
+
+```
+Custom Auth True Cost:
+  Direct: 3 engineers × 4 months = 12 engineer-months
+  Opportunity: 3 features delayed by 4 months
+             + Market share lost to faster competitors
+             + Developer time not on revenue features
+
+Question: Is custom auth worth all of that?
+```
+
+## Opportunity Cost Patterns
+
+### The "Free" Trap
+
+Nothing is free if it consumes time:
+
+```
+Scenario: "We can build this ourselves instead of paying $10K for the tool"
+
+Analysis:
+- Tool cost: $10,000
+- Build time: 2 engineers × 2 weeks = 4 engineer-weeks
+- Engineer cost: ~$4,000/week fully loaded = $16,000
+- Maintenance: 1 week/quarter = $16,000/year ongoing
+
+True cost: $16K + ongoing maintenance > $10K + $0 maintenance
+Plus: What else could those engineers have built?
+```
+
+### The Sunk Cost Interaction
+
+Don't let sunk costs distort opportunity cost analysis:
+
+```
+BAD thinking:
+"We've already spent 6 months on this, we can't abandon it"
+(Sunk cost fallacy ignores opportunity cost of continuing)
+
+GOOD thinking:
+"Given where we are now, what's the best use of the NEXT 6 months?"
+(Fresh opportunity cost analysis from current state)
+```
+
+### The Hidden Alternative
+
+The status quo is always an alternative:
+
+```
+Proposal: Migrate to Kubernetes
+Alternatives considered: ECS, Nomad, K8s
+Missing alternative: Don't migrate, improve current system
+
+Full analysis should include:
+- Cost of migration (all options)
+- Cost of staying put (often undervalued)
+- Opportunity cost of engineers doing migration vs. features
+```
+
+### Time as the Scarcest Resource
+
+Time opportunity cost is often highest:
+
+```
+"Quick meeting, only 30 minutes"
+
+For 8-person meeting:
+- Direct cost: 30 min × 8 = 4 person-hours
+- Opportunity cost: 4 hours not spent on focused work
+- Context switching cost: 15 min recovery × 8 = 2 more hours
+- True cost: ~6 person-hours of productivity
+
+Question: Is this meeting worth 6 hours of productivity?
+```
+
+## Application Areas
+
+### Feature Prioritization
+
+```markdown
+## Opportunity Cost Analysis: Feature A vs. B
+
+| Factor | Feature A | Feature B |
+|--------|-----------|-----------|
+| Dev time | 4 weeks | 2 weeks |
+| Revenue impact | $50K/month | $30K/month |
+| Time to value | 4 weeks | 2 weeks |
+
+If we build A first:
+- We get A in 4 weeks
+- We get B in 6 weeks
+- 2 extra weeks without B = $60K foregone
+
+If we build B first:
+- We get B in 2 weeks
+- We get A in 6 weeks
+- 2 extra weeks without A = $100K foregone
+
+Decision: Build A first despite higher dev cost (higher opportunity cost of delay)
+```
+
+### Build vs. Buy
+
+```markdown
+## Build vs. Buy: Monitoring System
+
+Build:
+- Development: $200K (4 engineers × 6 months)
+- Maintenance: $80K/year
+- Time to production: 6 months
+- Opportunity cost: Features those engineers would have built
+
+Buy (Datadog):
+- License: $50K/year
+- Integration: $30K (2 engineers × 1 month)
+- Time to production: 1 month
+- Opportunity cost: None significant
+
+5-year TCO:
+- Build: $200K + ($80K × 5) + opportunity cost = $600K + opportunity
+- Buy: ($50K × 5) + $30K = $280K
+
+Decision: Buy unless unique requirements justify 2x+ cost
+```
+
+### Technical Debt
+
+```markdown
+## Technical Debt Opportunity Cost
+
+Current state: 20% of engineering time on maintenance
+Proposed: 3-month refactoring project
+
+Analysis:
+- 3 months of refactoring = no features for 3 months
+- After refactoring: 10% time on maintenance (saves 10%)
+- Break-even: When does saved maintenance = investment?
+
+If team = 10 engineers:
+- Investment: 10 × 3 = 30 engineer-months
+- Monthly savings: 10 × 10% = 1 engineer-month
+- Break-even: 30 months
+
+Opportunity cost: Features not built during 3-month refactoring
+Real question: Are those features worth more than 30+ months of 10% overhead?
+```
+
+### Hiring Decisions
+
+```markdown
+## Hiring Opportunity Cost
+
+Choice: Hire senior engineer at $250K
+Alternative: Two mid-level at $300K total
+
+Analysis:
+- Senior: Higher immediate productivity, mentorship
+- Two mid: More throughput long-term, redundancy
+
+Opportunity cost of senior:
+- Fewer total engineers
+- Less coverage/redundancy
+- Longer ramp-up if they leave
+
+Opportunity cost of two mid:
+- More management overhead
+- Longer to complex projects
+- Training investment
+
+Decision depends on: Current team composition, project complexity, growth stage
+```
+
+## Opportunity Cost Template
+
+```markdown
+# Opportunity Cost Analysis: [Decision]
+
+## The Choice
+What we're considering: [Primary option]
+Resource commitment: [Time, money, people]
+
+## Alternatives
+What else could we do with these resources?
+
+| # | Alternative | Resource Use | Direct Value | Strategic Value |
+|---|-------------|--------------|--------------|-----------------|
+| 1 | [Primary choice] | [X] | [Value] | [Strategic] |
+| 2 | [Alternative 1] | [X] | [Value] | [Strategic] |
+| 3 | [Alternative 2] | [X] | [Value] | [Strategic] |
+| 4 | Do nothing | [X] | [Value] | [Strategic] |
+
+## Opportunity Cost Calculation
+
+Best foregone alternative: [Which one]
+Value of that alternative: [Quantified if possible]
+
+## True Cost of Primary Choice
+- Direct cost: [Resources consumed]
+- Opportunity cost: [Value of foregone alternative]
+- Total: [Sum]
+
+## Decision
+Is [primary choice] worth [total cost]?
+[Reasoning]
+
+## Reversibility
+If we're wrong, can we change course? At what cost?
+```
+
+## Mental Shortcuts
+
+### The "What Else?" Question
+
+Always ask: "If we didn't do this, what would we do instead?"
+
+### The 10x Test
+
+If opportunity cost is 10x the direct cost, rethink the decision.
+
+### The Time Value Multiplier
+
+Engineer time often has 3-5x multiplier in opportunity cost vs. dollar cost.
+
+### The Status Quo Alternative
+
+Always include "change nothing" as an explicit alternative.
+
+## Verification Checklist
+
+- [ ] Explicitly stated the choice and resource commitment
+- [ ] Listed at least 3 alternatives (including status quo)
+- [ ] Valued each alternative (even roughly)
+- [ ] Identified the best foregone alternative
+- [ ] Calculated opportunity cost explicitly
+- [ ] Made decision accounting for full cost
+- [ ] Considered reversibility
+
+## Key Questions
+
+- "What are we NOT doing by choosing this?"
+- "Is the 'free' option actually free?"
+- "What would we do with these resources otherwise?"
+- "What's the value of our next-best alternative?"
+- "Is this worth more than everything we're giving up?"
+- "Have we included the status quo as an option?"
+
+## Economic Wisdom
+
+"There is no such thing as a free lunch." — Milton Friedman
+
+Every choice has a cost, even if it's not written on an invoice. The cost is what you gave up to make that choice. Recognizing opportunity cost transforms how you evaluate decisions.
+
+"The cost of a thing is the amount of what I will call life which is required to be exchanged for it." — Henry David Thoreau
+
+For engineers: substitute "engineering time" for "life" — it's your most valuable and constrained resource.