@polderlabs/bizar 10.7.1 → 10.7.2

package/.claude/skills/thinking-kepner-tregoe/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: thinking-kepner-tregoe
+description: Use when a defect is selective (some endpoints/regions/users/times affected, not all) and the cause is unclear — map what IS vs IS-NOT affected; the boundary contrast points at the root cause.
+---
+
+# Kepner-Tregoe Problem Analysis
+
+## Overview
+
+Kepner-Tregoe (KT) is a structured root-cause method. **This skill focuses on Problem Analysis (PA) — the IS/IS-NOT boundary contrast — which is the high-value KT process for debugging.** When a defect is *selective* (some cases affected, others not), the boundary between IS and IS-NOT reveals the distinction that points at the root cause.
+
+Decision Analysis (DA) and Potential Problem Analysis (PPA) are de-emphasized here. For pure decision-making among alternatives, use `thinking-opportunity-cost`. For risk anticipation before a change, use `thinking-pre-mortem`. Those skills are purpose-built for those tasks; KT's DA/PPA add overhead without unique mechanism.
+
+Situation Analysis (SA) is retained as a lightweight triage step when facing multiple concerns, but it is not a required preamble — jump directly to PA when the problem is already clear.
+
+**Core Principle:** The boundary between what IS affected and what IS NOT affected encodes the root cause. Find the distinction, find the cause.
+
+## When to Use
+
+- A defect is **selective**: affects some endpoints/regions/users/times but NOT others — there is an IS-vs-IS-NOT boundary to contrast
+- The cause is unclear and not obvious from a stack trace, error message, or a single recent change
+- Multiple possible causes exist and you need a systematic way to narrow them
+- A complex situation has multiple concerns that need triage before diving in
+
+Decision flow:
+
+```
+Defect is selective (not 100%)? → No → IS/IS-NOT has no signal; use direct debugging or thinking-systems
+                                → Yes → Cause obvious from stack trace/recent change? → Yes → Just fix it
+                                                                                      → No → APPLY KT PROBLEM ANALYSIS
+```
+
+## When NOT to Use
+
+- **The failure is uniform** (affects 100% of requests/everything) — there is no IS-vs-IS-NOT boundary to contrast; PA gives no signal. Use `thinking-systems` or direct debugging.
+- **The cause is already obvious** from a stack trace, error message, or a single recent change — just fix it; IS/IS-NOT is overhead here.
+- **A pam hypothesis is cheaply testable** — test it (`thinking-occams-razor`) before building a full specification matrix.
+- **Pure decision-making with no deviation to diagnose** — use `thinking-opportunity-cost`, not KT's Decision Analysis.
+- **Risk assessment for a planned change** — use `thinking-pre-mortem`, not KT's Potential Problem Analysis.
+
+## Trigger Card
+
+When a defect is selective (some cases affected, others not) and the cause is unclear:
+
+1. **State the problem precisely** — what is the deviation? In what object? Where/when does it occur?
+2. **Map IS vs IS-NOT** — what IS affected vs what IS NOT, side by side. The boundary is the signal.
+3. **Find the distinction** — what is different about the IS cases vs the IS-NOT cases? That distinction IS the cause.
+
+Skip if the failure is uniform (100%) — there's no boundary to contrast; use direct debugging. If the cause is obvious from a stack trace or recent change, just fix it. For a single cheaply-testable hypothesis, test it first.
+
+## Procedure
+
+### Step 1 (optional): Situation Analysis — Triage Multiple Concerns
+
+Only when facing several problems at once. List all concerns, separate them if compound, and prioritize by Timing/Impact/Trend:
+
+| Concern | Timing | Impact | Trend | Priority |
+|---------|--------|--------|-------|----------|
+| API latency spike | Urgent | High | Worsening | P0 |
+| Checkout errors | Soon | High | Stable | P1 |
+
+For each concern, decide: Problem Analysis (PA), or delegate to another skill.
+
+### Step 2: State the Problem Precisely
+
+Describe the deviation from expected behavior with specificity:
+
+```
+"API response time increased from 200ms to 800ms for /checkout endpoint,
+US-East only, starting Monday 9 AM, affecting ~30% of requests."
+```
+
+### Step 3: Build the IS/IS-NOT Matrix
+
+Specify the problem across four dimensions. The power is in the **distinction** column — what's unique about the IS side?
+
+| Dimension | IS (affected) | IS NOT (not affected) | Distinction |
+|-----------|---------------|----------------------|-------------|
+| **WHAT** — object | /checkout endpoint | /cart, /product, /user | Payment processing |
+| **WHAT** — defect | 4x latency increase | Errors, timeouts, data corruption | Performance only |
+| **WHERE** — location | Production US-East | EU, US-West, staging | Single region |
+| **WHERE** — on object | Database query phase | Auth, validation, serialization | DB layer |
+| **WHEN** — first seen | Monday 9:00 AM | Before Monday, after 6 PM | Business hours |
+| **WHEN** — pattern | During checkout submit | During browsing, cart add | Write operations |
+| **EXTENT** — how many | ~30% of requests | 100% of requests | Intermittent |
+| **EXTENT** — trend | Stable since Tuesday | Getting worse | Plateaued |
+
+### Step 4: Extract Distinctions
+
+For each row, ask: "What's unique or distinctive about the IS side compared to the IS-NOT side?"
+
+```
+Distinctions:
+- Only /checkout (payment processing) — not other endpoints
+- Only US-East (specific DB replica) — not other regions
+- Only during business hours (load-related?) — not off-peak
+- Only ~30% of requests (specific query pattern?) — not all
+- Started Monday 9 AM — what changed?
+```
+
+### Step 5: Identify Changes
+
+What changed in, on, around, or about the distinctions near the first observation time?
+
+```
+Changes near Monday 9 AM:
+- Payment provider SDK updated (Sunday night deploy)
+- Database index rebuild scheduled (Sunday maintenance)
+- New fraud detection rules enabled (Monday 8:45 AM)
+```
+
+### Step 6: Generate and Test Possible Causes
+
+Each candidate cause must explain BOTH the IS and the IS-NOT:
+
+| Possible Cause | Explains IS? | Explains IS-NOT? | Verdict |
+|----------------|-------------|------------------|---------|
+| Fraud rules adding DB queries | ✓ Only checkout, only write ops | ✓ Not other endpoints | **Pursue** |
+| Payment SDK change | ✓ Only checkout | ✗ Would affect all regions | Ruled out |
+| Index rebuild | ✓ DB layer | ✗ Would affect all queries | Ruled out |
+
+### Step 7: Verify the True Cause
+
+Design a test to confirm or rule out the leading candidate:
+
+```
+Verification for "Fraud detection rules":
+1. Check: Rules enabled 8:45 AM (matches timeline)
+2. Check: Rules only on checkout (matches scope)
+3. Test: Disable rules in canary, measure latency
+4. Examine: Query logs for fraud check queries
+```
+
+## Output Contract
+
+A completed KT Problem Analysis produces:
+
+1. **Problem Statement** — specific, measurable deviation
+2. **IS/IS-NOT Matrix** — all four dimensions with distinctions extracted
+3. **Changes List** — what changed near the distinctions around the first observation
+4. **Cause Test Table** — each candidate tested against IS and IS-NOT
+5. **Confirmed Root Cause** — with verification evidence
+6. **If used, SA Triage** — prioritized concern list with assigned processes
+
+## Anti-Patterns
+
+| Anti-Pattern | Symptom | Correction |
+|---|---|---|
+| **KT on uniform failure** | Running PA when 100% of requests fail | No boundary to contrast; use direct debugging or `thinking-systems` |
+| **Over-specifying the matrix** | Filling every IS/IS-NOT cell for a simple bug | Stop when the distinction is clear; don't ritualize |
+| **DA/PPA sprawl** | Running full Decision Analysis or Potential Problem Analysis for routine tasks | Redirect to `thinking-opportunity-cost` (decisions) or `thinking-pre-mortem` (risks) |
+| **Skipping cause testing** | Pursuing the first plausible cause without testing against IS-NOT | Every cause must explain BOTH IS and IS-NOT |
+| **SA as mandatory preamble** | Running full Situation Analysis before every PA | Jump directly to PA when the problem is already clear |
+| **Ignoring the distinction** | Building the matrix but not extracting what's unique about IS | The distinction IS the signal; without it, the matrix is just a table |

package/.claude/skills/thinking-leverage-points/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: thinking-leverage-points
+description: Use when picking where to intervene in a system and tuning parameters keeps not sticking—rank candidate interventions by Meadows' hierarchy and choose the highest-leverage point you can move.
+---
+
+# Leverage Points
+
+## Overview
+
+Donella Meadows' "Places to Intervene in a System" ranks intervention points by their power to change behavior. Most effort goes into low-leverage moves (parameters, buffers) when higher-leverage points (rules, goals, structure) change behavior with less force. This is the canonical home of the 12-level hierarchy—other skills (`thinking-systems`, `thinking-feedback-loops`) reference it instead of duplicating it.
+
+**Core Principle:** Higher in the hierarchy = more leverage, but more resistance. Find the highest leverage point you can actually move.
+
+## When to Use
+
+- Choosing where to focus engineering effort on a system you can already see
+- Incremental tweaks (timeouts, buffer sizes, more instances) keep not solving the problem
+- Deciding between a pam parameter change and a structural fix
+
+```
+Want to change system behavior?
+  → Stuck tuning parameters with no lasting effect? → MOVE UP THE HIERARCHY
+  → Found the lever but the change won't stick?     → look for a balancing loop resisting it
+```
+
+## When NOT to Use
+
+- You haven't yet located the cause or mapped the system → use `thinking-systems` first; you can't rank interventions on a system you don't understand.
+- A single low-level parameter genuinely is the fix (e.g., a wrong timeout value) → just change it; don't manufacture a paradigm shift.
+- The decision is a one-off with no system behind it → this hierarchy adds nothing.
+
+## Trigger Card
+
+When tuning parameters keeps not sticking and you need to pick where to intervene:
+
+1. **Identify the system goal** — what is the system trying to do? This is the highest-leverage point.
+2. **Scan the hierarchy top-down** — from goals/rules/power down to parameters. Don't start at the bottom.
+3. **Intervene at the highest feasible point** — pick the highest-leverage point you can actually change, not the easiest.
+
+If a single low-level parameter genuinely is the fix (wrong timeout value), just change it. If there's no system behind the decision, skip — this hierarchy adds nothing.
+
+## The 12 Leverage Points (Low to High)
+
+### Level 12: Constants and Parameters (LOWEST LEVERAGE)
+
+**What:** Numbers—budgets, rates, thresholds, timeouts
+
+**Examples:**
+- Adjusting cache TTL
+- Changing retry counts
+- Modifying timeout values
+- Tweaking rate limits
+
+**Why low leverage:** Parameters rarely change behavior fundamentally. The system absorbs parameter changes and continues its pattern.
+
+```
+Intervention: Increase server timeout from 30s to 60s
+Result: Slow requests succeed, but root cause remains
+Leverage: Very low—masks symptom, doesn't fix system
+```
+
+### Level 11: Buffer Sizes
+
+**What:** Stabilizing stocks—queues, caches, inventories
+
+**Examples:**
+- Queue depth limits
+- Connection pool sizes
+- Memory allocations
+- Batch sizes
+
+**Why low leverage:** Buffers absorb fluctuations but don't change system dynamics. Bigger buffer = slower response to change.
+
+```
+Intervention: Increase message queue size
+Result: Handles traffic spikes, but processing lag grows
+Leverage: Low—buys time but doesn't address throughput
+```
+
+### Level 10: Stock-and-Flow Structures
+
+**What:** Physical architecture—how things are connected
+
+**Examples:**
+- Database schema
+- Service topology
+- Network architecture
+- Team structure
+
+**Why medium leverage:** Hard to change once built; design matters but is often locked in.
+
+```
+Intervention: Add read replica to reduce DB load
+Result: Significant improvement in read performance
+Leverage: Medium—structural change, but within existing paradigm
+```
+
+### Level 9: Delays
+
+**What:** Time lags in feedback loops
+
+**Examples:**
+- Deployment pipeline duration
+- Feedback cycle time
+- Onboarding time
+- Release frequency
+
+**Why medium leverage:** Shortening delays makes systems more responsive and stable. Many oscillation problems are actually delay problems.
+
+```
+Intervention: Reduce deployment time from 2 hours to 10 minutes
+Result: Faster feedback, fewer bugs reaching production
+Leverage: Medium-high—changes system responsiveness fundamentally
+```
+
+### Level 8: Balancing Feedback Loops
+
+**What:** Negative feedback that counteracts change
+
+**Examples:**
+- Auto-scaling rules
+- Circuit breakers
+- Quality gates
+- Alerting thresholds
+
+**Why medium-high leverage:** Strengthening balancing loops increases stability; weakening them enables change.
+
+```
+Intervention: Implement circuit breaker with automatic recovery
+Result: Failures isolated, cascade prevention
+Leverage: Medium-high—changes failure dynamics
+```
+
+### Level 7: Reinforcing Feedback Loops
+
+**What:** Positive feedback that amplifies change
+
+**Examples:**
+- Growth loops (viral, network effects)
+- Technical debt spirals
+- Talent attraction/attrition cycles
+- Performance improvement loops
+
+**Why high leverage:** Reinforcing loops drive exponential growth or collapse. Controlling gain = controlling trajectory.
+
+```
+Intervention: Create "fix broken windows" culture that reinforces quality
+Result: Quality begets quality, technical debt decreases
+Leverage: High—self-sustaining improvement
+```
+
+### Level 6: Information Flows
+
+**What:** What signal is surfaced, and where
+
+**Examples:**
+- Surfacing a previously-hidden metric (queue depth, error budget, p99)
+- Logging the value that was silently defaulting
+- Making a failure mode observable instead of swallowed
+
+**Why high leverage:** A component can only respond to what it can see. Adding a feedback signal where one was missing changes behavior without changing any logic.
+
+```
+Intervention: Emit and alert on cache hit-rate that was previously invisible
+Result: Regression caught immediately instead of after an outage
+Leverage: High—behavior change through visibility
+```
+
+### Level 5: System Rules
+
+**What:** Constraints the system enforces—what's allowed, required, or rejected
+
+**Examples:**
+- A required CI gate / merge check
+- A schema or contract that rejects invalid input at the boundary
+- A deployment policy (canary, required rollback path)
+- A rate limit or quota
+
+**Why high leverage:** Rules define what's even possible. Change the rule and a whole class of behavior changes or becomes impossible.
+
+```
+Intervention: Make the type checker / schema validation a hard CI gate
+Result: An entire class of bug can no longer reach production
+Leverage: High—changes what's acceptable
+```
+
+### Level 4: Self-Organization
+
+**What:** Ability of the system to change its own structure
+
+**Examples:**
+- Plugin/extension points instead of hardcoded behavior
+- Services that can register/discover each other dynamically
+- Auto-scaling and self-healing instead of fixed topology
+- Schema/config that the system can evolve safely
+
+**Why very high leverage:** Systems that can adapt their own structure survive change; rigid systems eventually break.
+
+```
+Intervention: Replace a hardcoded dispatch table with a plugin registry
+Result: New behavior added without touching the core; the system evolves
+Leverage: Very high—enables adaptation
+```
+
+### Level 3: System Goals
+
+**What:** What the system is actually optimizing for
+
+**Examples:**
+- The objective a scheduler/optimizer maximizes
+- The SLO the system is built to hold
+- The success metric a pipeline is tuned against
+
+**Why very high leverage:** Everything downstream serves the goal. Optimizing for the wrong target reliably produces the wrong behavior, no matter how good the parts are.
+
+```
+Intervention: Change a cache eviction goal from "max hit rate" to "bound tail latency"
+Result: Different eviction policy, different downstream behavior entirely
+Leverage: Very high—redirects all effort
+```
+
+### Level 2: Paradigm (Mindset)
+
+**What:** The shared assumptions from which goals and architecture arise
+
+**Examples:**
+- "Cache everything" vs "Cache only what's measured hot"
+- "Microservices always" vs "Right tool for context"
+- "Avoid failure" vs "Design for graceful degradation"
+
+**Why transformational:** Paradigms are upstream of goals, rules, and structure. Shift the paradigm, transform the system.
+
+```
+Intervention: Shift from "retry until success" to "fail fast + shed load"
+Result: Retry storms become impossible; the whole failure mode changes
+Leverage: Transformational—changes what's thinkable
+```
+
+### Level 1: Transcending Paradigms (HIGHEST LEVERAGE)
+
+**What:** The ability to change paradigms, recognizing no paradigm is "true"
+
+**Examples:**
+- Recognizing that current best practices are temporary
+- Ability to hold multiple paradigms simultaneously
+- Knowing when to abandon a paradigm
+
+**Why highest leverage:** Freedom from paradigm lock-in enables choosing the right paradigm for each context.
+
+```
+Mastery: Recognize when "microservices always" became dogma
+         Choose monolith when it's right
+Result: Optimal architecture for each situation
+Leverage: Highest—freedom from ideological constraints
+```
+
+## Applying Leverage Points
+
+### Step 1: Identify Current Interventions
+
+Where are you currently trying to create change?
+
+```markdown
+Current interventions:
+- Increasing server count (Level 11 - buffers)
+- Adjusting timeout parameters (Level 12 - parameters)
+- Adding monitoring (Level 6 - information flows)
+```
+
+### Step 2: Map to Hierarchy
+
+Plot on the hierarchy to see leverage distribution:
+
+```
+High Leverage    [3] Goals
+                 [5] Rules
+                 [6] Information ← Monitoring
+                 [7] Reinforcing loops
+Medium           [8] Balancing loops
+                 [9] Delays
+                 [10] Structure
+Low Leverage     [11] Buffers ← Server count
+                 [12] Parameters ← Timeouts
+```
+
+### Step 3: Look Higher
+
+For each low-leverage intervention, ask: "What's the higher-leverage version?"
+
+| Low Leverage | Ask | Higher Leverage |
+|--------------|-----|-----------------|
+| More instances | Why do we need more capacity? | Fix the inefficient algorithm/query (structure) |
+| Longer timeouts | Why are things slow? | Reduce a delay in the pipeline (Level 9) |
+| Patch each bug instance | Why does this class recur? | Make it unrepresentable / add a CI gate (10, 5) |
+
+### Step 4: Assess Feasibility
+
+Higher leverage usually means more cost or more resistance. Evaluate before committing:
+
+```markdown
+Intervention: Make schema validation a hard gate (Level 5)
+Leverage: High—blocks a whole bug class
+Cost/resistance: Touches every caller; needs migration of existing data
+Strategy: Validate in warn-only mode first, then flip to enforce
+```
+
+### Step 5: Choose Highest Feasible Leverage
+
+Select the highest-leverage intervention you can actually execute now.
+
+## Common Patterns
+
+### The Parameter Trap
+
+Endlessly tuning parameters when the real issue is structural:
+
+```
+Symptom: Constantly adjusting cache TTLs, retry counts, timeouts
+Reality: Architecture doesn't match access patterns
+Solution: Redesign the data flow (Level 10) instead of tuning parameters
+```
+
+### The Information Unlock
+
+A component behaves badly because a signal is invisible to it:
+
+```
+Symptom: A regression ships repeatedly and is only caught downstream
+Reality: The relevant metric is never surfaced
+Solution: Emit + alert on it (Level 6)—behavior corrects without new logic
+```
+
+### The Goal Inversion
+
+The system optimizes a proxy that diverges from the real objective:
+
+```
+Symptom: Cache maximizes hit-rate but tail latency is terrible
+Reality: The optimization target is wrong
+Solution: Change the goal to "bound p99" (Level 3)
+```
+
+### The Paradigm Shift
+
+Sometimes the whole frame is wrong:
+
+```
+Symptom: Recurring retry storms despite tuning retry counts
+Reality: "Retry until success" is the wrong paradigm under load
+Solution: Shift to "fail fast + shed load" (Level 2)
+```
+
+## Leverage Points for Common Problems
+
+| Problem | Low-Leverage Response | High-Leverage Alternative |
+|---------|----------------------|---------------------------|
+| System too slow | Add caching (11) | Fix algorithm; surface latency in feedback (6, 10) |
+| Too many bugs slip through | More manual testing (12) | Make the check a required gate / CI rule (5) |
+| Repeated cascading failures | Bigger timeouts (12) | Add circuit breaker / backpressure loop (8) |
+| Retry storms under load | Lower retry count (12) | Change the retry paradigm: fail fast + shed (2) |
+| Same bug class recurs | Patch each instance (12) | Make it unrepresentable via type/schema (10, 4) |
+| Hidden, wrong defaults | Tune the value (12) | Make the config visible/validated (6, 5) |
+
+## Verification Checklist
+
+- [ ] Identified current intervention points
+- [ ] Mapped interventions to leverage hierarchy
+- [ ] Asked "what's the higher-leverage version?" for each
+- [ ] Assessed feasibility vs. leverage tradeoff
+- [ ] Selected highest feasible leverage point
+- [ ] Considered resistance and how to address it
+- [ ] Have strategy for paradigm-level resistance if applicable
+
+## Key Questions
+
+- "What level of leverage am I operating at?"
+- "What's one level higher I could try?"
+- "Why hasn't this parameter tuning fixed the problem?"
+- "What information is missing that would change behavior?"
+- "What rule change would make this unnecessary?"
+- "What goal are we actually optimizing for?"
+- "What paradigm is constraining our thinking?"
+
+## Meadows' Wisdom
+
+"People who manage to intervene in systems at the level of paradigm hit a leverage point that totally transforms systems."
+
+"Magical leverage points are not easily accessible, even if we know where they are. There are no cheap tickets to mastery."
+
+The highest leverage requires the most skill and often the most patience. But knowing where leverage exists helps you stop wasting effort at the bottom of the hierarchy.