@polderlabs/bizar 10.7.1 → 10.7.2

package/.claude/skills/thinking-theory-of-constraints/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: thinking-theory-of-constraints
+description: Use when optimizing latency or throughput in a pipeline and one stage dominates—focus all effort on that single bottleneck, since speeding up the others changes nothing until it's fixed.
+---
+
+# Theory of Constraints
+
+## Overview
+
+The Theory of Constraints (TOC), from Eliyahu Goldratt's "The Goal," says a throughput-limited system has exactly one constraint setting its rate. Optimizing anything else is wasted effort—often counterproductive. Find the bottleneck, exploit it, subordinate everything else to it, and only then elevate it.
+
+**Core Principle:** A chain is only as strong as its weakest link. Strengthening any other link does nothing.
+
+## When to Use
+
+- Latency optimization where one stage dominates the time budget
+- Throughput optimization where one stage caps the rate
+- A pipeline where work piles up before one specific stage
+
+```
+Trying to improve latency/throughput?
+  → Have you identified the constraint? → no → FIND THE CONSTRAINT FIRST
+  → Are you optimizing a non-constraint? → yes → STOP, FOCUS ON CONSTRAINT
+  → Is the constraint working at 100%?   → no → EXPLOIT BEFORE ELEVATING
+```
+
+## When NOT to Use
+
+- **No single stage dominates** (latency/load is spread roughly evenly, or many stages are near 100%) → there is no one constraint to exploit. Use `thinking-systems` to model the interactions instead.
+- The problem is correctness, not throughput → this is the wrong lens; debug the fault.
+- The bottleneck is already obvious and cheap to fix → just fix it; skip the five steps.
+- "Bottleneck" shifts every run (it's contention/coupling, not a fixed stage) → that's a systems problem, not a constraint.
+
+## The Five Focusing Steps
+
+### Step 1: Identify the Constraint
+
+Find the one thing limiting the system:
+
+```markdown
+## Constraint Identification
+
+System: Software delivery pipeline
+
+Potential constraints:
+| Stage | Capacity | Utilization | Queue Time |
+|-------|----------|-------------|------------|
+| Requirements | 10/week | 60% | 0 days |
+| Development | 8/week | 95% | 3 days |
+| Code Review | 5/week | 100% | 5 days |←CONSTRAINT
+| Testing | 12/week | 40% | 0 days |
+| Deployment | 20/week | 20% | 0 days |
+
+Constraint: Code Review
+Evidence: 100% utilization, 5-day queue, lowest throughput
+```
+
+**How to find the constraint:**
+- Highest utilization
+- Longest queue/wait time
+- Lowest throughput rate
+- Where work piles up
+- What people complain about waiting for
+
+### Step 2: Exploit the Constraint
+
+Get maximum output from the constraint without spending money:
+
+```markdown
+## Exploiting the Constraint
+
+Constraint: Code Review (5/week capacity)
+
+Exploitation strategies:
+| Strategy | Effort | Impact |
+|----------|--------|--------|
+| Never let reviewers wait for reviewable PRs | Low | +10% |
+| Batch small PRs together | Low | +15% |
+| Clear review criteria to reduce back-and-forth | Low | +20% |
+| Prioritize reviews over other reviewer work | Medium | +10% |
+| Remove unnecessary review requirements | Low | +15% |
+
+Total potential: 5/week → 8/week (60% increase, no new resources)
+```
+
+**Exploitation questions:**
+- Is the constraint ever idle? Why?
+- Is the constraint doing any unnecessary work?
+- Is the constraint's output ever wasted downstream?
+- Can we reduce setup/changeover time?
+- Can we improve quality at the constraint (less rework)?
+
+### Step 3: Subordinate Everything Else
+
+Non-constraints should serve the constraint:
+
+```markdown
+## Subordination
+
+Every other stage should optimize FOR code review, not for itself.
+
+Requirements:
+- DON'T: Maximize requirement throughput
+- DO: Pace requirements to match code review capacity
+- DO: Ensure requirements are clear (reduce review iterations)
+
+Development:
+- DON'T: Maximize development output
+- DO: Produce review-ready code at the rate review can handle
+- DO: Spend extra time on clarity (save reviewer time)
+
+Testing:
+- DON'T: Maximize testing efficiency
+- DO: Be ready to test immediately when reviews complete
+- DO: Provide feedback that helps reviewers learn
+
+Counter-intuitive: Keeping developers busy beyond review capacity
+                   creates work-in-progress that HURTS throughput
+```
+
+**Subordination principle:**
+Local optimization of non-constraints often hurts global throughput. A 100% utilized developer feeding a 100% utilized reviewer creates a queue that slows everything.
+
+### Step 4: Elevate the Constraint
+
+If exploitation isn't enough, invest in increasing constraint capacity:
+
+```markdown
+## Elevating the Constraint
+
+Current constraint capacity: 8/week (after exploitation)
+Required capacity: 12/week
+
+Elevation options:
+| Option | Cost | Capacity Gain |
+|--------|------|---------------|
+| Hire dedicated reviewer | $150K/year | +4/week |
+| Train more reviewers | $10K training | +2/week |
+| Adopt review tooling | $5K/year | +1/week |
+| Pair reviewing | Process change | +3/week |
+
+Recommendation: Training + tooling first ($15K for +3/week)
+                Then hire if still insufficient
+```
+
+**Elevation timing:**
+Only elevate after exploitation is maxed out. Elevating is expensive; exploitation is cheap.
+
+### Step 5: Prevent Inertia (Go Back to Step 1)
+
+When you elevate, the constraint often moves:
+
+```markdown
+## Constraint Movement
+
+Before: Code Review was constraint (5/week)
+After elevation: Code Review does 12/week
+
+New constraint search:
+| Stage | Capacity | Utilization |
+|-------|----------|-------------|
+| Requirements | 10/week | 100% | ←NEW CONSTRAINT
+| Development | 15/week | 80% |
+| Code Review | 12/week | 80% |
+| Testing | 12/week | 100% | ←OR THIS ONE |
+
+System bottleneck moved—repeat the process.
+```
+
+## Finding Constraints
+
+### Types of Constraints
+
+| Type | Examples | How to Find |
+|------|----------|-------------|
+| Physical | Machine capacity, server limits | Utilization metrics |
+| Policy | Approval requirements, rules | Process analysis |
+| Market | Customer demand | Sales/pipeline data |
+| Time | Fixed deadlines | Schedule analysis |
+| Knowledge | Expert availability | Skill matrix |
+
+### Constraint Indicators
+
+```
+Signs of a constraint:
+✓ Work queues up before this stage
+✓ Downstream stages have idle time
+✓ Increasing input doesn't increase output
+✓ This stage is always at full capacity
+✓ Small improvements here have large system effects
+
+Signs of a non-constraint:
+✓ Often has idle time
+✓ Improvement has no system effect
+✓ Work flows through without queuing
+```
+
+## TOC Application Patterns
+
+### Performance Optimization
+
+```markdown
+## System Performance Analysis
+
+Request flow:
+API Gateway → Auth → App Logic → Database → Response
+
+Latency breakdown:
+| Component | Latency | % of Total |
+|-----------|---------|------------|
+| API Gateway | 5ms | 2% |
+| Auth | 10ms | 4% |
+| App Logic | 30ms | 12% |
+| Database | 200ms | 80% | ←CONSTRAINT
+| Response | 5ms | 2% |
+
+Constraint: Database
+
+Wrong approach: Optimize app logic (12% of latency)
+Right approach: Focus 100% on database optimization
+                Query optimization, caching, indexing, read replicas
+```
+
+### Batch/Data Pipeline Throughput
+
+```markdown
+## Pipeline Throughput Analysis
+
+Stage flow:
+Ingest → Parse → Transform → Enrich (external API) → Write
+
+Throughput analysis:
+| Stage | Rate (rec/s) | Utilization |
+|-------|--------------|-------------|
+| Ingest | 50,000 | 20% |
+| Parse | 30,000 | 35% |
+| Transform | 20,000 | 50% |
+| Enrich (external API) | 2,000 | 100% | ←CONSTRAINT
+| Write | 40,000 | 25% |
+
+System throughput is capped at 2,000 rec/s by the enrichment call.
+Parallelizing parse/transform does nothing—it just grows the queue before Enrich.
+
+Exploit: batch the API calls, cache repeat lookups, drop redundant enrichments.
+Subordinate: pace upstream stages to 2,000 rec/s; don't build WIP.
+Elevate (only if exploit insufficient): add API concurrency / a second provider.
+```
+
+### Concurrency / Lock Contention
+
+```markdown
+## Contention Analysis
+
+Symptom: throughput plateaus far below CPU capacity.
+
+| Resource | Wait time | Notes |
+|----------|-----------|-------|
+| CPU | low | cores idle |
+| Global mutex | HIGH | every request serializes here | ←CONSTRAINT
+| DB pool | low | |
+
+The single hot lock is the constraint; adding workers makes contention worse.
+Exploit: shorten the critical section to the minimum.
+Elevate: shard the lock / switch to a lock-free or per-key structure.
+```
+
+## Theory of Constraints Template
+
+```markdown
+# TOC Analysis: [System/Process]
+
+## System Definition
+What flows through this system: [Work items, requests, features]
+Goal: [What throughput matters]
+
+## Constraint Identification
+
+| Stage | Capacity | Utilization | Queue Time | Throughput |
+|-------|----------|-------------|------------|------------|
+| | | | | |
+
+**Identified Constraint:** [Stage]
+**Evidence:** [Why this is the constraint]
+
+## Step 2: Exploit
+
+How to maximize constraint output without investment:
+| Exploitation | Effort | Expected Gain |
+|--------------|--------|---------------|
+| | | |
+
+## Step 3: Subordinate
+
+How should non-constraints support the constraint?
+| Stage | Current Behavior | Should Change To |
+|-------|------------------|------------------|
+| | | |
+
+## Step 4: Elevate (if needed)
+
+If exploitation isn't sufficient:
+| Elevation Option | Cost | Capacity Gain |
+|------------------|------|---------------|
+| | | |
+
+## Step 5: Next Constraint
+
+After elevation, where will the constraint move?
+[Prediction]
+```
+
+## Verification Checklist
+
+- [ ] Identified the single constraint (not multiple "bottlenecks")
+- [ ] Have data supporting the constraint identification
+- [ ] Maximized exploitation before considering elevation
+- [ ] Non-constraints are subordinated (not locally optimized)
+- [ ] Not investing in non-constraint improvements
+- [ ] Monitoring for constraint movement
+
+## Key Questions
+
+- "What's the ONE thing limiting throughput?"
+- "Is the constraint ever idle? Why?"
+- "Are we improving a non-constraint while ignoring the constraint?"
+- "Are non-constraint improvements building inventory?"
+- "What should the rest of the system do to serve the constraint?"
+- "If we improve this, where will the constraint move?"
+
+## Goldratt's Wisdom
+
+"Every action that brings the company closer to its goal is productive. Every action that does not bring a company closer to its goal is not productive."
+
+"An hour lost at a bottleneck is an hour lost forever. An hour saved at a non-bottleneck is a mirage."
+
+"The sum of local optimums is not equal to the global optimum."
+
+Optimizing everywhere is the same as optimizing nowhere. Find the constraint. Make it work. That's all that matters until the constraint moves.

package/.claude/skills/thinking-thought-experiment/SKILL.md

@@ -0,0 +1,354 @@
+---
+name: thinking-thought-experiment
+description: You need to trace how a system would fail or behave at a scale you can't cheaply test or measure. Use to imagine the scenario and walk the consequence chain step by step.
+---
+
+# Thought Experiments
+
+## Overview
+
+Thought experiments use imagination to test ideas when direct experimentation is impractical, impossible, or premature. Einstein's elevator, Schrödinger's cat, and the trolley problem have advanced physics and philosophy. In engineering, thought experiments help evaluate designs, explore edge cases, and stress-test decisions before implementation.
+
+**Core Principle:** Structured imagination is a tool. When you can't test in reality, test in your mind with discipline.
+
+## The Core Reframe
+
+When you can't run the real experiment — the failure is too rare, the scale too large, the decision too one-way — you can still run it in your head with discipline: fix the conditions, then trace the consequence chain one step at a time until something breaks. The value is in the *step-by-step trace*, not in the verdict you jumped to.
+
+## When to Use
+
+- Tracing a failure mode you can't easily trigger (primary DB down at peak, region outage)
+- Reasoning about behavior at a scale you can't currently reach (10x/100x traffic)
+- Evaluating a one-way architectural decision before committing
+- Exploring edge cases that are expensive or impossible to reproduce
+
+Decision flow:
+
+```
+Need to understand how something behaves?
+  → Can you cheaply test or measure it? → yes → DO THAT (stop here)
+  → Is the real test too rare/large/irreversible? → yes → THOUGHT EXPERIMENT
+```
+
+## When NOT to Use
+
+- **If you can cheaply test or measure it, test it.** A thought experiment is a substitute for empiricism, not a replacement — a load test, a feature flag, a query against real data, or a pam spike beats imagined consequences every time. Reach for this skill only when the real experiment is genuinely out of reach.
+- **For adversarial "how would an attacker break this" analysis, use thinking-red-team** — it has the structured attack-surface and findings format. Don't reinvent it here.
+
+## Trigger Card
+
+When you need to trace how a system would behave at a scale you can't cheaply test:
+
+1. **Define the scenario precisely** — what changed? What's different from normal operation? Set initial conditions.
+2. **Walk the consequence chain step by step** — given these conditions, what does the system do next? Then what? Then what? Be mechanistic, not hand-wavy.
+3. **Derive what you'd need to check** — what observation would confirm or refute this chain? If you can test one link cheaply, test it.
+
+If you can cheaply test or measure the real thing (load test, feature flag, query against real data), do that instead — a thought experiment is a substitute for empiricism, not a replacement. For adversarial "how would an attacker break this" analysis, use `thinking-red-team`.
+
+## Types of Thought Experiments
+
+### 1. The Hypothetical Scenario
+
+Imagine a specific situation and trace consequences:
+
+```
+"What if we had 100x current traffic tomorrow?"
+"What if our primary database failed right now?"
+"What if a competitor copied our core feature?"
+```
+
+### 2. The Extreme Case
+
+Push a parameter to its limit:
+
+```
+"What happens with 0 users? 1 billion users?"
+"What if latency was 0? What if it was 10 seconds?"
+"What if this team was 1 person? 100 people?"
+```
+
+### 3. The Counterfactual
+
+Imagine the opposite of reality:
+
+```
+"What if we hadn't chosen microservices?"
+"What if we didn't have this dependency?"
+"What if our main customer segment didn't exist?"
+```
+
+### 4. The Role Reversal
+
+Think from a different perspective:
+
+```
+"What would a malicious actor do with this system?"
+"How would a new hire experience this codebase?"
+"What would a competitor do with our technology?"
+```
+
+### 5. The Time Shift
+
+Move forward or backward in time:
+
+```
+"How will this look in 5 years?"
+"If we had known this a year ago, what would we have done?"
+"What will we wish we had built today?"
+```
+
+## The Thought Experiment Process
+
+### Step 1: Define the Experiment
+
+State clearly what you're testing:
+
+```markdown
+## Thought Experiment: Database Failure Resilience
+
+Question: How would our system behave if the primary database
+         became unavailable for 30 minutes during peak traffic?
+
+Variables:
+- Database state: Unavailable
+- Duration: 30 minutes
+- Traffic: Peak (3x normal)
+- Preparation time: None (unexpected)
+```
+
+### Step 2: Set the Initial Conditions
+
+Describe the starting state precisely:
+
+```markdown
+## Initial Conditions
+
+System state:
+- 10,000 active users
+- 500 RPS to database
+- No circuit breaker currently
+- 10-second connection timeout
+- No read replica failover configured
+
+User behavior:
+- Users will retry failed requests
+- ~50% will leave after 2 failures
+```
+
+### Step 3: Trace the Consequences
+
+Walk through what happens step by step:
+
+```markdown
+## Consequence Chain
+
+T+0s: Database becomes unavailable
+T+0-10s: Requests queue waiting for connection
+T+10s: Connection timeouts start
+T+10-30s: App servers accumulate waiting requests
+T+30s: Thread pools exhausted
+T+30s-2m: Cascading timeouts to upstream services
+T+2m: Load balancer health checks fail
+T+2m: Alerts fire (too late - damage done)
+T+2-30m: Service completely unavailable
+T+30m: Database returns, but app servers need restart
+T+35m: Service gradually recovers
+T+1h: Backlog of failed requests processed
+```
+
+### Step 4: Identify Insights
+
+What did you learn?
+
+```markdown
+## Insights
+
+1. Circuit breaker would limit cascade (need to implement)
+2. Thread pool exhaustion is the failure mode (need limits)
+3. Alerts fire too late (need proactive monitoring)
+4. Recovery is slow (need automated recovery)
+5. User experience is terrible (need graceful degradation)
+```
+
+### Step 5: Derive Actions
+
+What should you do based on this experiment?
+
+```markdown
+## Actions
+
+| Insight | Action | Priority |
+|---------|--------|----------|
+| No circuit breaker | Implement circuit breaker | High |
+| Thread pool exhaustion | Add connection limits | High |
+| Late alerts | Add DB latency monitoring | Medium |
+| Slow recovery | Automate failover | Medium |
+| Poor UX | Implement degraded mode | Medium |
+```
+
+## Thought Experiment Patterns
+
+### The Failure Mode Analysis
+
+```markdown
+## Thought Experiment: What if [component] fails?
+
+For each critical component:
+- API Gateway fails: [Trace consequences]
+- Auth service fails: [Trace consequences]
+- Cache layer fails: [Trace consequences]
+- Message queue fails: [Trace consequences]
+
+Template for each:
+1. What fails immediately?
+2. What fails within 1 minute?
+3. What's the blast radius?
+4. How would we know?
+5. How would we recover?
+```
+
+### The Adversarial Analysis
+
+> For real security work, prefer **thinking-red-team** (structured attack surface + reproducible-attack-path findings). Use the sketch below only as a pam lens, not a substitute.
+
+```markdown
+## Thought Experiment: Attacker Perspective
+
+"I am a malicious actor with [access level]. How would I cause maximum damage?"
+
+Scenario 1: External attacker with no access
+- What public endpoints are vulnerable?
+- What would a DDoS look like?
+- What data could I infer from public behavior?
+
+Scenario 2: Compromised user account
+- What can I access beyond my own data?
+- Can I escalate privileges?
+- What's the blast radius of one compromised account?
+
+Scenario 3: Malicious insider
+- What would a rogue employee do?
+- What access is over-provisioned?
+- What audit trails would catch this?
+```
+
+### The Scale Experiment
+
+```markdown
+## Thought Experiment: 10x Scale
+
+Current: 10,000 users, 100 RPS
+Imagined: 100,000 users, 1,000 RPS
+
+What breaks?
+- [ ] Database connections (pool exhaustion at ~300)
+- [ ] Single-threaded workers (CPU bound at ~500 RPS)
+- [ ] Memory per request (OOM at ~800 RPS)
+- [ ] Network bandwidth (saturated at ~1500 RPS)
+
+What doesn't break?
+- [x] Stateless API servers (horizontally scalable)
+- [x] CDN-served assets (already edge-cached)
+- [x] Read-heavy queries (can add replicas)
+
+First constraint to address: Database connection pooling
+```
+
+### The Timeline Experiment
+
+```markdown
+## Thought Experiment: 3 Years From Now
+
+It's 2027. Our system is [successful/struggling]. Why?
+
+Success scenario:
+- What architectural decisions paid off?
+- What did we avoid that would have hurt us?
+- What did we invest in that scaled well?
+
+Struggle scenario:
+- What technical debt crushed us?
+- What market change did we miss?
+- What architecture couldn't adapt?
+
+Present implications:
+- What should we invest in now for 2027 success?
+- What should we avoid now to prevent 2027 failure?
+```
+
+## Thought Experiment Template
+
+```markdown
+# Thought Experiment: [Title]
+
+## Question
+What am I trying to understand?
+[Precise question]
+
+## Setup
+Initial conditions:
+- [Condition 1]
+- [Condition 2]
+
+Variables being tested:
+- [Variable 1]: [Value in experiment]
+- [Variable 2]: [Value in experiment]
+
+## Thought Experiment
+[Step-by-step trace of what happens]
+
+T+0: [Initial event]
+T+X: [Consequence]
+T+Y: [Next consequence]
+...
+T+end: [Final state]
+
+## Observations
+What happened in the experiment?
+- [Observation 1]
+- [Observation 2]
+
+## Insights
+What did I learn?
+- [Insight 1]
+- [Insight 2]
+
+## Implications
+What should I do differently?
+- [Action 1]
+- [Action 2]
+
+## Limitations
+What didn't this experiment capture?
+- [Limitation 1]
+- [Limitation 2]
+```
+
+## Verification Checklist
+
+- [ ] Defined a clear, specific question
+- [ ] Set up realistic initial conditions
+- [ ] Traced consequences systematically
+- [ ] Considered second-order effects
+- [ ] Identified non-obvious insights
+- [ ] Derived actionable implications
+- [ ] Acknowledged experiment limitations
+
+## Key Questions
+
+- "What happens if [extreme scenario]?"
+- "How would this look from [different perspective]?"
+- "What would [5 years from now] tell us about this decision?"
+- "What if the opposite were true?"
+- "What's the worst thing that could happen?"
+- "How would a [malicious actor/competitor/novice] interact with this?"
+
+## Einstein's Approach
+
+"A thought experiment is a device with which one performs an intentional, structured process of intellectual deliberation in order to speculate, within a specifiable problem domain, about potential consequents (or antecedents) for a designated antecedent (or consequent)."
+
+More simply: Imagine a scenario, trace what happens, and learn.
+
+"I have no special talents. I am only passionately curious."
+
+Thought experiments are curiosity with structure. Ask "what if?" systematically, trace the answer carefully, and you'll see what testing in reality would eventually show you—sometimes years sooner.