@polderlabs/bizar 10.7.0 → 10.7.2

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

@@ -0,0 +1,330 @@
+---
+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.