@polderlabs/bizar 10.7.2 → 10.10.0

package/.claude/skills/thinking-margin-of-safety/SKILL.md

@@ -1,330 +0,0 @@
----
-name: thinking-margin-of-safety
-description: Use when provisioning capacity, setting a timeout/limit, or committing to an estimate under uncertainty. Size a buffer to the cost of being wrong instead of optimizing to the edge.
----
-
-# Margin of Safety
-
-## Overview
-
-Margin of Safety, borrowed from Benjamin Graham's investment philosophy and structural engineering, is the practice of building in buffers to account for unknown unknowns. In a world of uncertainty, systems optimized to the edge are brittle. Robust systems have slack, reserves, and room for error.
-
-**Core Principle:** Build in buffers. The world is uncertain. Systems without margin fail when stressed.
-
-## When to Use
-
-- Capacity planning
-- Deadline and timeline estimation
-- Architecture design
-- Resource allocation
-- Risk management
-- SLA commitments
-- Infrastructure provisioning
-- Any commitment under uncertainty
-
-Decision flow:
-
-```
-Provisioning, setting a limit, or committing an estimate under uncertainty?
-  → Is there real uncertainty AND a cost to under-provisioning? → yes → SIZE A BUFFER TO THE FAILURE COST
-  → Are you optimizing to the edge to save a little? → yes → ADD SLACK unless the breach is cheap
-  → Estimate could be 2x off? → factor that into the buffer
-```
-
-## When NOT to Use
-
-- **Cheap, instant, and reversible to adjust.** If under-provisioning is detected immediately and fixed at near-zero cost (auto-scaling that reacts in seconds, a limit you can bump live), a fat static buffer just wastes resources — let the system absorb it.
-- **The buffer's cost exceeds the expected breach cost.** Margin isn't free; when `cost(buffer) > probability(breach) × cost(breach)`, the buffer is the wrong call. Right-size, don't max out.
-- **You can eliminate the uncertainty instead of padding it.** If the real number is measurable or lookup-able, get it — a measured value beats a padded guess. (Margin covers *residual* uncertainty, not laziness about checking.)
-- **This is a stopping-criterion problem, not a buffer problem.** If the question is "how long do I keep searching/optimizing?", that's `thinking-bounded-rationality` (set a good-enough threshold), not margin. *Margin sizes the buffer on a number; bounded-rationality decides when to stop looking for the number.*
-
-## Trigger Card
-
-When provisioning capacity, setting a limit, or committing to an estimate under uncertainty:
-
-1. **Estimate the base number** — what's your best estimate without padding?
-2. **Assess the cost of being wrong** — if you undershoot, what breaks and how badly? The higher the cost, the larger the margin.
-3. **Size the buffer to the uncertainty** — add enough margin that the worst plausible miss doesn't cause a catastrophe. Commit with the buffered number.
-
-If you can eliminate the uncertainty by measuring or looking up the real number, do that instead — a measured value beats a padded guess. If the question is "when do I stop searching?", that's `thinking-bounded-rationality`, not margin.
-
-## The Margin of Safety Framework
-
-### Step 1: Identify Your Estimate
-
-What's your best guess for the requirement?
-
-```
-Estimate: Need 100 requests/second capacity
-Estimate: Project will take 6 weeks
-Estimate: Need 500GB storage for year 1
-```
-
-### Step 2: Quantify Your Uncertainty
-
-How confident are you, and what could you be missing?
-
-```markdown
-## Uncertainty Analysis
-
-| Factor | Your Estimate | Uncertainty | Possible Range |
-|--------|---------------|-------------|----------------|
-| Traffic | 100 RPS | ±50% | 50-150 RPS |
-| Spike multiplier | 3x | ±100% | 1.5x-6x |
-| Growth rate | 20%/year | ±50% | 10-30%/year |
-| Unknown unknowns | - | +50-100% | - |
-```
-
-### Step 3: Calculate Required Margin
-
-Different contexts need different margins:
-
-| Context | Typical Margin | Rationale |
-|---------|---------------|-----------|
-| Capacity planning | 2-3x | Traffic spikes unpredictable |
-| Time estimation | 1.5-2x | Everything takes longer |
-| Infrastructure | 2x headroom | Scaling takes time |
-| SLA commitment | 1.5x buffer | Reputation at stake |
-| New/unknown domain | 2-3x | High uncertainty |
-| Well-understood domain | 1.3-1.5x | Lower uncertainty |
-
-### Step 4: Apply Margin
-
-```
-Base estimate: 100 RPS
-Margin: 2x (moderate uncertainty, spikes possible)
-Provision: 200 RPS capacity
-
-Base estimate: 6 weeks
-Margin: 1.5x (experienced team, some unknowns)
-Commit: 9 weeks
-```
-
-### Step 5: Monitor and Adjust
-
-Track actuals against estimates to calibrate future margins:
-
-```markdown
-## Calibration Log
-
-| Estimate | Margin Applied | Actual | Margin Accuracy |
-|----------|----------------|--------|-----------------|
-| 100 RPS | 2x (200) | 180 | Adequate |
-| 6 weeks | 1.5x (9) | 10 weeks | Insufficient |
-| 500 GB | 2x (1TB) | 400 GB | Excessive |
-
-Insight: Time estimates need higher margin; storage was overprovisioned
-```
-
-## Margin Patterns
-
-### Capacity Margin
-
-```markdown
-## Capacity Planning with Margin
-
-Base load: 1,000 RPS
-Peak multiplier: 3x (historical)
-Margin for unknowns: 1.5x
-Margin for growth: 1.3x (6 months runway)
-
-Required capacity: 1,000 × 3 × 1.5 × 1.3 = 5,850 RPS
-Round up: 6,000 RPS
-
-Rationale: Can handle 6x normal load, or 4x peak, or growth + peak
-```
-
-### Time Margin
-
-```markdown
-## Project Estimation with Margin
-
-Task estimates:
-- Feature A: 2 weeks
-- Feature B: 3 weeks
-- Integration: 1 week
-- Testing: 1 week
-Base total: 7 weeks
-
-Adjustments:
-- Optimistic bias: +30%
-- Unknowns: +20%
-- Dependencies: +15%
-Margin total: 1.65x
-
-Commitment: 7 × 1.65 = 11.5 → 12 weeks
-
-Rule of thumb: Hofstadter's Law - "It always takes longer than you expect,
-               even when you take into account Hofstadter's Law."
-```
-
-### Financial Margin
-
-```markdown
-## Budget with Margin
-
-Infrastructure estimate:
-- Compute: $5,000/month
-- Storage: $2,000/month
-- Network: $1,000/month
-Base: $8,000/month
-
-Margin considerations:
-- Traffic growth: +25%
-- Unplanned incidents: +15%
-- New features: +20%
-
-Budget request: $8,000 × 1.6 = $12,800/month
-Actual budget: $13,000/month (round up)
-```
-
-### Design Margin
-
-```markdown
-## Architectural Margin
-
-Connection pool:
-- Normal usage: 50 connections
-- Peak: 100 connections
-- Margin: 2x peak
-- Configure: 200 connections
-
-Queue depth:
-- Normal processing: 1,000 messages
-- Burst: 10,000 messages
-- Margin: 2x burst
-- Configure: 20,000 max depth
-
-Timeout:
-- P99 latency: 500ms
-- Margin: 2x
-- Set timeout: 1000ms
-```
-
-## When to Use Different Margins
-
-### High Margin (2-3x)
-
-- New domain or technology
-- Critical system (failure is very costly)
-- External dependencies (unpredictable)
-- Customer-facing SLAs
-- Irreversible commitments
-
-### Moderate Margin (1.5-2x)
-
-- Familiar domain with some unknowns
-- Internal systems (can recover from issues)
-- Controlled dependencies
-- Reversible decisions
-
-### Low Margin (1.2-1.5x)
-
-- Well-understood domain
-- Historical data available
-- Low consequence of being wrong
-- Short time horizons
-- Easy to adjust
-
-### No Margin (Optimize to Edge)
-
-Almost never appropriate for:
-- Public commitments
-- Production systems
-- External dependencies
-
-Acceptable for:
-- Internal experiments
-- Temporary systems
-- Cost optimization after proving stable
-
-## The Cost of Margin
-
-Margin isn't free. Balance:
-
-```markdown
-## Margin Cost-Benefit
-
-High margin:
-+ Handles unexpected loads
-+ Reduces stress/heroics
-+ Enables growth without emergency scaling
-- Higher infrastructure cost
-- Potentially wasted resources
-
-Low margin:
-+ Lower cost
-+ Efficient resource use
-- Risk of outages
-- Constant firefighting
-- Technical debt from pam fixes
-
-Sweet spot: Margin where cost of buffer < expected cost of margin-breach × probability
-```
-
-## Margin of Safety Template
-
-```markdown
-# Margin of Safety Analysis: [Context]
-
-## Base Estimate
-What: [What you're estimating]
-Estimate: [Your point estimate]
-Confidence: [How confident you are]
-
-## Uncertainty Factors
-| Factor | Impact | Probability | Adjustment |
-|--------|--------|-------------|------------|
-| [Factor 1] | +X% | Medium | |
-| [Factor 2] | +Y% | Low | |
-| Unknown unknowns | +Z% | - | |
-
-## Margin Calculation
-Base: [X]
-Uncertainty multiplier: [1.X]
-Context multiplier: [1.Y] (high/medium/low stakes)
-Total margin: [X × all multipliers]
-
-## Final Commitment/Design
-With margin: [Final number]
-Rationale: [Why this margin]
-
-## Monitoring Plan
-How will you know if margin is adequate/excessive?
-- [Metric to track]
-- [Threshold for concern]
-- [Review cadence]
-```
-
-## Verification Checklist
-
-- [ ] Identified base estimate
-- [ ] Quantified uncertainty factors
-- [ ] Selected appropriate margin for context
-- [ ] Applied margin to commitment/design
-- [ ] Considered cost of margin vs. cost of breach
-- [ ] Have monitoring to validate margin adequacy
-- [ ] Calibrating based on actual outcomes
-
-## Key Questions
-
-- "What happens if my estimate is wrong by 2x?"
-- "How much margin does this uncertainty warrant?"
-- "Am I building for best case or realistic case?"
-- "What's the cost of being wrong vs. cost of margin?"
-- "Have I accounted for unknown unknowns?"
-- "Am I optimizing to the edge when I shouldn't be?"
-
-## Graham's Wisdom
-
-"The margin of safety is always dependent on the price paid."
-
-In engineering: The margin needed depends on the cost of failure. Critical systems need more margin. Experiments can run leaner.
-
-"Confronted with the challenge to distill the secret of sound investment into three words, we venture the motto, Margin of Safety."
-
-In systems: When in doubt, build in margin. The cost of over-provisioning is usually much less than the cost of under-provisioning when things go wrong.
-
-"The function of the margin of safety is, in essence, that of rendering unnecessary an accurate estimate of the future."
-
-You don't need to predict perfectly if you have adequate margin. Margin is insurance against your own estimation errors.