@complexthings/superpowers-agent 9.2.1 → 10.0.1

package/skills/problem-solving/meta-pattern-recognition/SKILL.md

@@ -1,116 +0,0 @@
----
-name: meta-pattern-recognition
-description: Spot patterns appearing in 3+ domains to find universal principles. Use when you notice the same problem recurring across different contexts, when teams independently discover "identical" solutions, when experiencing déjà vu in problem-solving, or when you want to actively extract transferable principles. Triggers on phrases like "this feels familiar," "haven't we solved this before?", "same thing keeps happening," or "why do all these systems look the same?"
-metadata:
-  version: 1.2.0
----
-
-# Meta-Pattern Recognition
-
-## Overview
-
-When the same shape appears in 3+ genuinely different domains, you've found something universal. Name it, and you unlock it everywhere.
-
-**Core principle:** Find patterns in how patterns emerge — then apply them where nobody has looked yet.
-
-Two modes: **passive** (recognize a pattern already recurring) and **active** (force patterns to surface through deliberate techniques).
-
-## Quick Reference
-
-| Pattern | Abstract Form | Seen In |
-|---------|--------------|---------|
-| CPU/DB/HTTP caching | Store frequently-accessed data closer to consumer | LLM prompt caching, CDN, memoization |
-| Layering (network/OS/storage) | Separate concerns into abstraction levels | Architecture, org structure, compiler stages |
-| Queuing (message/task/request) | Decouple producer from consumer via buffer | Event systems, async I/O, print spoolers |
-| Pooling (connection/thread/object) | Reuse expensive resources rather than recreate | Memory allocators, worker pools, license servers |
-| Rate limiting / circuit breakers | Bound consumption to prevent exhaustion | Token budgets, backpressure, admission control |
-| Retry with exponential backoff | Respect the system you depend on | HTTP clients, DB reconnect, social negotiation |
-
-## Passive Mode: Recognize a Recurring Pattern
-
-1. **Spot repetition** — Same shape appears in 3+ distinct domains (not just 3 modules in one system)
-2. **Extract abstract form** — State the pattern using zero domain-specific vocabulary
-3. **Map variation points** — Where does it *have to* vary, and why? (reveals the true structure)
-4. **Hunt new applications** — Where does this pattern apply that nobody has tried yet?
-
-**Example:**
-
-Pattern spotted: Rate limiting (APIs), traffic shaping (networks), circuit breakers (microservices), admission control (OSes)
-
-Abstract form: *Bound resource consumption to prevent exhaustion*
-
-Variation points: what resource, what measurement window, what happens when exceeded (reject / queue / degrade)
-
-New application: LLM token budgets — same pattern prevents context-window exhaustion; variant is "soft limit + graceful degradation" rather than hard rejection.
-
-## Active Mode: Force Patterns to Emerge
-
-Use when you want to *generate* insights, not just spot them.
-
-**Collision Zone Thinking** — Force two unrelated concepts together:
-> "What if rate limiting applied to human attention, not API calls?"
-The collision reveals a third concept neither domain had.
-
-**The Medium Swap** — Apply a solution from one domain directly to another:
-> TCP backpressure → LLM token streaming; biological immune memory → anomaly detection
-
-**The Inversion Exercise** — Flip the core assumption:
-> "What if caching *slowed* things down?" → reveals cache invalidation cost, stale data risk
-
-**The Scale Game** — Test at 1000x bigger, 1000x smaller, instant, or year-long:
-> Patterns that hold at extremes are truly universal; those that break reveal hidden assumptions.
-
-**The 2+2=5 Framework** — Find synergistic combinations:
-> Caching + streaming = speculative prefetch (a third concept neither had alone)
-
-## Emergence Types
-
-Watch for these when patterns arise unexpectedly:
-
-- **Divergence** — Two concepts collide → third option neither implied ("creates" + "removes" = "transforms")
-- **Tension** — Sustained contradiction generates insight rather than resolving (consistency vs. availability → eventually-consistent as a new idea, not a compromise)
-- **Cascade** — One pattern recognition triggers a chain ("buffer" = RAM, Git staging, async queues, human short-term memory — all one pattern)
-- **Void** — What's *not* connected reveals what's missing ("Why is there no pattern here?" often signals unsolved problems)
-- **Meta** — Patterns in how patterns form ("Why do resource-management patterns always have the same 3 variation points?")
-
-## Quality Check
-
-Before claiming you've found a universal pattern:
-
-- [ ] Does it appear in 3+ **genuinely different domains**? (not 3 places in one codebase)
-- [ ] Can you state it with **zero domain-specific vocabulary**?
-- [ ] Have you identified at least **2 variation points** explaining why it looks different per domain?
-- [ ] Does applying it somewhere **new produce a useful result**?
-- [ ] Can you name **what it replaces** — what separate mental models collapse into one?
-
-## Simplification Cascades
-
-The best meta-patterns eliminate complexity. When you find a universal principle, ask: **"If this is true, what do we no longer need?"**
-
-> If all resource limits are "bound consumption to prevent exhaustion" → rate limiting, circuit breakers, and admission control no longer need separate mental models.
-
-A good cascade eliminates 3+ previously separate concepts.
-
-## Productive Tensions
-
-Don't resolve contradictions too quickly — they generate patterns.
-
-When two things seem to conflict, ask: What third concept does this tension reveal? Does this tension appear in other domains?
-
-**Preserve failed pattern-matches.** They reveal where the abstraction breaks and what the true variation points are.
-
-## Red Flags You're Missing Meta-Patterns
-
-- "This problem is unique" — probably not; look harder
-- Multiple teams solving "different" problems with identical solutions
-- Reinventing wheels across domains without cross-pollination
-- "Haven't we done something like this before?"
-- Resolving contradictions too fast (destroying a pattern generator)
-- Discarding failed pattern-attempts (they contain the variation data)
-
-## Remember
-
-- 3+ domains = likely universal; 5+ = probably foundational
-- Abstract form (no jargon) reveals new applications — the vocabulary you choose shapes what you find next
-- Variation points explain *why* it looks different, not just *how*
-- Productive tensions and failures are data, not dead ends

package/skills/problem-solving/meta-pattern-recognition/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:problem-solving/meta-pattern-recognition",
-    "title": "Meta-Pattern Recognition",
-    "aliases": [
-        "meta-pattern-recognition",
-        "problem-solving/meta-pattern-recognition"
-    ]
-}

package/skills/problem-solving/scale-game/SKILL.md

@@ -1,222 +0,0 @@
----
-name: scale-game
-description: Test at extremes (1000x bigger/smaller, instant/year-long) to expose fundamental truths hidden at normal scales. Use this skill whenever someone asks "will this scale?", "what happens at production load?", "what if 1000 users hit this simultaneously?", or when validating architecture, reviewing algorithms, designing systems, or reasoning about capacity. Also use proactively when you see O(n²) algorithms, shared mutable state, synchronous APIs, or in-memory data accumulation — any pattern whose behavior changes with scale.
-metadata:
-  version: 3.1.0
----
-
-# Scale Game
-
-## Overview
-
-Test your approach at extreme scales to find what breaks and what surprisingly survives.
-
-**Core principle:** Properties invisible at normal scales dominate at extreme scales. An O(n²) algorithm is fine at n=100 and catastrophic at n=1,000,000. Test at extremes to find the fundamentals before production does.
-
-This is a thought experiment technique — most scale tests take seconds, not machines. The goal is insight, not measurement.
-
-## Origins
-
-This technique has deep roots across science and engineering:
-
-- **Galileo (1638):** Dropping two cannonballs from the Leaning Tower — testing at "different weights" exposed that Aristotle's theory (heavier falls faster) was wrong. Extremes falsified conventional wisdom.
-- **Einstein (1905):** "What would I see if I chased a light beam at light speed?" — an impossible-to-run experiment that led directly to special relativity. The extreme (v = c) revealed a contradiction in classical physics.
-- **Fermi Estimation:** Reasoning by order of magnitude to establish bounds — "how many piano tuners in Chicago?" is the mathematical equivalent of the scale game: work from first principles to a number, then ask if the number makes sense at different scales.
-- **Jeff Dean at Google:** "Numbers Everyone Should Know" established a canonical scale reference — L1 cache (0.5 ns) vs. cross-continental round trip (150 ms) is a 300,000,000× difference. Knowing these numbers lets you reason about systems at scale without building them.
-- **Netflix Chaos Monkey (2011):** Institutionalized extreme failure testing. If your system can't survive random instance death, it can't survive production.
-
-## Quick Reference
-
-| Scale Dimension | Test At Zero/Minimum | Test At Maximum | What It Reveals |
-|-----------------|---------------------|-----------------|-----------------|
-| Volume | 0 items, 1 item | 1B items, unbounded | Algorithmic complexity class (O(n²) vs O(n log n)) |
-| Concurrency | 1 user, sequential | 1M simultaneous users | Race conditions, lock contention, resource exhaustion |
-| Speed / Latency | Instant (in-process) | 150ms cross-continent | Whether synchronous calls become blocking bottlenecks |
-| Duration / Time | Milliseconds | Years of continuous runtime | Memory leaks, state accumulation, index bloat |
-| Failure Rate | Never fails | Always fails | Error handling coverage, circuit breaker needs |
-| Data Size | Empty payload | Terabyte payload | Buffer limits, streaming requirements |
-| Cardinality | 1 tenant / 1 type | 100M tenants / 10K types | Partitioning needs, per-entity overhead |
-| Depth / Nesting | Flat structure | 1000-level deep tree | Stack overflow, recursive algorithm limits |
-| Network | LAN (microseconds) | Satellite link (600ms + packet loss) | Protocol choices, retry logic, idempotency |
-| Cost | Free tier | $1M/month | Whether the design is economically viable at scale |
-| Team Size | 1 engineer | 1000 engineers | Conway's Law — architecture mirrors team communication |
-| Service Composition | 1 service | 150 chained services | Tail latency amplification (see Dynamo case study) |
-
-## Process
-
-1. **Pick dimension** — What could vary extremely? (Volume, concurrency, time, failure rate, data size, cost, team size)
-2. **Establish baseline** — What does the system do at normal scale? What is "steady state"?
-3. **Test minimum** — What if this was zero, one, or 1000× smaller/faster/fewer?
-4. **Test maximum** — What if this was 1000× bigger/slower/more?
-5. **Note what breaks** — Where do limits appear? What assumptions fail first?
-6. **Note what survives** — What's fundamentally sound regardless of scale?
-7. **Classify the failure mode** — Graceful degradation (slows down, sheds load) or catastrophic collapse (crashes, data loss, cascading failure)?
-
-## Examples
-
-### Example 1: Error Handling
-**Normal scale:** "Handle errors when they occur" seems fine  
-**At 0.001% failure rate × 1B requests/day:** = 1M errors/day. Logging each one crashes the log aggregator.  
-**Reveals:** Need to make errors impossible (stronger types), batch/sample errors at scale, or design for error as the steady state (chaos engineering mindset)
-
-### Example 2: Synchronous APIs
-**Normal scale (single server):** Direct function calls work. 1ms latency is negligible.  
-**At global scale (client in Sydney, server in Virginia):** 150ms network latency. Synchronous call blocks a thread for 150ms. At 1000 concurrent users, you need 1000 threads just waiting on network.  
-**Reveals:** Async/messaging becomes a survival requirement, not an optimization. A shared lock that takes 1ms at 10 users takes 10 seconds at 10,000 users.
-
-### Example 3: In-Memory State
-**Normal duration (hours/days):** Works fine  
-**At years of continuous runtime:** A 1KB/request memory leak at 1M requests/day = 1TB accumulated in ~3 years.  
-**Reveals:** Need explicit eviction (TTL, LRU), persistence with periodic cleanup, or bounded data structures. Can't rely on "restart to fix."
-
-### Example 4: Naive Database Counter
-**Normal scale (100 writes/sec):** `SELECT count, UPDATE count WHERE id=X` works fine  
-**At high write scale (100K writes/sec):** Row-level lock creates a bottleneck. All writes serialize. Throughput collapses.  
-**Reveals:** Sharded counters (N rows, randomly selected, aggregated on read). Google's AppEngine Sharded Counter is the canonical solution.
-
-### Example 5: Monolith to Microservices
-**Small team (5 engineers):** Monolith is fast, simple, easy to refactor  
-**At 500 engineers:** Deployment conflicts, slow builds, inability to independently release. Any commit blocks everyone.  
-**Reveals:** Conway's Law — system architecture mirrors team communication structure. Scale of *team* is a dimension, not just traffic.
-
-### Example 6: Big-O as Algorithmic Scale Game
-**Bubble sort at n=10:** 100 operations, imperceptible  
-**Bubble sort at n=1,000,000:** 10^12 operations — days of runtime  
-**Binary search at n=1,000,000:** ~20 operations  
-**Reveals:** The choice of algorithm doesn't matter at small n. It matters catastrophically at large n. Big-O notation is a formal scale game: classify behavior as n → ∞.
-
-### Example 7: Chained Microservices Tail Latency
-**1 service at 99% reliability:** 1% of requests are slow — acceptable  
-**100 chained services each at 99% reliability:** `1 - 0.99^100 = 63.4%` of requests hit at least one slow service  
-**Reveals:** Tail latency amplifies multiplicatively in service chains. 99% per-service reliability is broken system reliability at scale. Design for P99.9, not P50. (See Dynamo case study below.)
-
-## Output Format
-
-When doing a scale game analysis, structure findings as:
-
-```
-Dimension tested: [volume / concurrency / duration / failure rate / cost / ...]
-Current assumption: [what the design assumes]
-At minimum scale: [behavior at zero/one/negligible]
-At maximum scale: [behavior at 1000× / extreme]
-Breaking point: [where the assumption fails]
-Failure mode: [graceful degradation or catastrophic collapse?]
-Insight: [what this reveals about the fundamental design]
-Action: [what to change, verify, or accept as a known limit]
-```
-
-**Example output:**
-```
-Dimension tested: duration
-Current assumption: user session tokens cached in memory, evicted on timeout
-At minimum scale: 1 active user — works perfectly
-At maximum scale: 10 years of operation at 1M users/day
-Breaking point: no TTL enforcement → tokens accumulate → OOM crash
-Failure mode: catastrophic (OOM kills process, logs all sessions out)
-Insight: in-memory session store has unbounded growth without explicit eviction
-Action: add TTL + LRU eviction, or move to Redis with expiry
-```
-
-## Common Anti-Patterns
-
-- **"It works in dev"** — Dev environments have tiny datasets, no concurrency, no memory pressure, and perfect network
-- **"Should scale fine"** — This phrase without a scale test means "I haven't thought about it"
-- **Only testing happy path scale** — Test failure at scale too. What happens when 10% of dependencies are down simultaneously?
-- **Mistaking load test for stress test** — Load test confirms expected behavior. Stress test finds the failure mode. You need both.
-- **Ignoring the cheap end** — Zero and one are often buggy (empty arrays, single-element edge cases, division by zero)
-- **Forgetting duration** — A system that passes a 1-hour load test may fail after 72 hours of soak testing
-- **Confusing throughput with latency** — High throughput with terrible tail latency is a broken system. Test P99 at scale, not averages.
-- **Stopping at the first breaking point** — Note the breaking point, then ask: does it fail gracefully or catastrophically?
-
-## Testing Spectrum (Related Formal Techniques)
-
-| Technique | What Scale Is Being Tested | Purpose |
-|-----------|---------------------------|---------|
-| **Load testing** | Volume at expected peak | Confirm system handles projected load |
-| **Stress testing** | Volume beyond expected peak | Find the breaking point and failure mode |
-| **Soak testing** | Duration (hours to days at steady load) | Reveal memory leaks, slow resource accumulation |
-| **Chaos engineering** | Failure rate (random instance/zone/region death) | Validate resilience when components fail |
-| **Property-based testing** | Input space (random + extreme edge cases) | Find cases the developer didn't think to write |
-| **Fermi estimation** | Back-of-envelope across dimensions | Sanity-check before building; identify order-of-magnitude problems |
-
-## Non-Software Applications
-
-The scale game applies in any domain where assumptions hold at one scale but fail at another:
-
-- **Physics:** Newton's laws work at human scales; break at relativistic speeds (Einstein) and quantum scales
-- **Economics:** "More is always better" breaks at scale — a market can have too much liquidity, creating instability
-- **Organizations:** Flat communication works at 10 people; fails at 150 (Dunbar's number) — hierarchy becomes necessary
-- **Security:** A password policy that annoys nobody at 10 users creates massive friction at 10M users, causing workarounds that defeat the policy
-- **Business strategy:** Amazon's "Working Backwards" — writing the press release before the code forces clarity on who the customer is and what success looks like at any scale
-
-## Real-World Case Studies
-
-Use these as calibration for your own scale estimates — they show how scale assumptions fail in production.
-
----
-
-### Pokémon GO: 50× the Expected Launch Traffic (2016)
-
-**What they planned:** Niantic estimated 1× baseline traffic, with worst-case at 5×.
-
-**What happened:** Within 15 minutes of the Australia/NZ launch, traffic surpassed all projections. Peak hit **50× the original target** — 10× their worst case. The Japan launch had **3× the US launch traffic**. Engineers had to expand Kubernetes clusters in-flight while millions were playing — adding 1,000+ nodes to a live system.
-
-**Scale game lesson:** Your "worst case" estimate is rarely the actual worst case. Ask: "What happens at 10× our worst-case estimate?" Make sure the answer is "we add capacity" not "we fail."
-
-*Source: Google Cloud blog, "Bringing Pokémon GO to life on Google Cloud," 2016.*
-
----
-
-### Amazon Dynamo: Designing for P99.9, Not the Mean (2007)
-
-**The math:** A single page render calls 150+ services. If each has 99% reliability, the probability that *at least one* is slow: `1 - 0.99^150 = 78%`. 78% of page renders hit at least one slow service — even though each service looks healthy in isolation.
-
-**Amazon's response:** Measure SLAs at P99.9. Design failure as the **normal case**, not the exception.
-
-> *"Many algorithms that perform reasonably well under low load and small datasets can explode in cost if either request rates increase, the dataset grows or the number of nodes in the distributed system increases."*
-> — Werner Vogels
-
-**Scale game lesson:** "What is P99.9 latency when 10 services in my call graph are each independently slow?"
-
-*Source: Amazon Dynamo paper, SOSP 2007.*
-
----
-
-### Jeff Dean's Latency Numbers: The Reference Scale Table
-
-The canonical reference for reasoning about distributed system scale:
-
-| Operation | Latency | Relative to L1 |
-|-----------|---------|----------------|
-| L1 cache reference | 0.5 ns | 1× |
-| L2 cache reference | 7 ns | 14× |
-| Main memory reference | 100 ns | 200× |
-| Read 4K randomly from SSD | 150,000 ns (150 µs) | 300,000× |
-| Round trip within same datacenter | 500,000 ns (500 µs) | 1,000,000× |
-| Disk seek | 10,000,000 ns (10 ms) | 20,000,000× |
-| Send packet CA → Netherlands → CA | 150,000,000 ns (150 ms) | 300,000,000× |
-
-**Key insight:** A cross-continental round trip is **300 million times slower** than an L1 cache hit. A disk seek is 20× slower than a datacenter round trip. These numbers determine whether synchronous APIs are viable and whether an algorithm that touches disk can meet a latency SLA.
-
-*Source: Jeff Dean / Peter Norvig; GitHub gist jboner/2841832.*
-
----
-
-### Twitter: Temporal Sharding Collapse
-
-**Original design:** Tweets from the same date range stored on the same shard — simple, predictable.
-
-**At scale:** One shard filled completely every **3 weeks**. Old shards received no traffic (severe load imbalance). The design that was simple at launch became structurally broken at volume — required a full architecture rebuild.
-
-**Scale game lesson:** "If our data grows at this rate, how full is each shard in 6 months? 2 years? Who handles writes once the shard is full?" Running that forward projection exposes the collapse point before you build it.
-
----
-
-## Remember
-
-- **Extremes reveal fundamentals** — The scale game is a truth-forcing function
-- **Test both directions** — Bigger AND smaller (zero and one are often the most revealing)
-- **The failure mode matters as much as the breaking point** — Graceful degradation vs. catastrophic collapse
-- **Thought experiments are free** — Most scale analysis takes minutes, not machines
-- **The dimension you don't test is the one that bites you in production**
-- **Big-O is a formal scale game** — If you know the complexity class, you know the scale behavior

package/skills/problem-solving/scale-game/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:problem-solving/scale-game",
-    "title": "Scale Game",
-    "aliases": [
-        "scale-game",
-        "problem-solving/scale-game"
-    ]
-}

package/skills/problem-solving/simplification-cascades/SKILL.md

@@ -1,113 +0,0 @@
----
-name: simplification-cascades
-description: Find one insight that eliminates multiple components - "if this is true, we don't need X, Y, or Z". Use when you see the same concept implemented multiple ways, a growing list of special cases, complexity spiraling with each new requirement, or code that keeps needing "one more" conditional branch. Also use when refactoring feels like whack-a-mole, when a config file keeps growing, or when you suspect a unifying abstraction exists but can't see it yet.
-metadata:
-  when_to_use: when implementing the same concept multiple ways, accumulating special cases, complexity is spiraling, or refactoring one thing keeps breaking others
-  version: 2.0.0
----
-
-# Simplification Cascades
-
-## What This Is
-
-A simplification cascade is a discovery: one unifying insight collapses multiple separate mechanisms, special cases, or components into one. The cascade effect matters — removing one concept makes others unnecessary, which reveals more to remove. The result is systems that are simultaneously smaller *and* more powerful.
-
-**Core test:** After the cascade, is there less total code — not just reorganized code?
-
-## How the Best Cascades in History Worked
-
-These aren't just examples. They're the template:
-
-- **Unix "everything is a file"**: Devices, pipes, sockets, processes — one `open/read/write/close` interface replaced dozens of specialized APIs
-- **Lisp "code = data"**: Programs and data share the same representation (S-expressions), making macros natural, reducing the language to ~7 primitives, eliminating a syntax/semantics split
-- **Monads**: What had been separate mechanisms — I/O, error handling, state, async, logging, parsing — became instances of one abstraction
-- **REST**: Resources + uniform interface (GET/POST/PUT/DELETE) replaced the proliferation of SOAP, CORBA, and custom RPC styles
-- **Lambda calculus**: Two operations (abstraction + application) encode all of computation
-
-The pattern: someone asked "what if all of these are actually the same thing?" — and the answer was yes.
-
-## Quick Diagnostic
-
-| Symptom | What to suspect |
-|---------|----------------|
-| Same thing implemented 5+ ways | Abstract the common pattern |
-| `if type == A / B / C / D` everywhere | Find the general case |
-| Complex rules with growing exceptions | Find the rule with no exceptions |
-| Excessive config options | Find defaults that cover 95% |
-| Refactoring feels like whack-a-mole | Missing a unifying concept |
-| "Don't touch that, it's complicated" | Complexity hiding an absent abstraction |
-| "We need one more case..." (repeating) | You haven't found the general case |
-| New requirements always need a new handler | Each requirement exposes missing abstraction |
-
-## The Discovery Process
-
-Cascades are found bottom-up, not designed top-down. You cannot force one.
-
-1. **Accumulate instances** — Don't abstract at 1 or 2 cases; wait for 3. (Fowler's Rule of Three: one is a fact, two is coincidence, three is a pattern.)
-2. **List the variations** — What's actually being implemented multiple ways?
-3. **Ask the unifying question** — "What if these are all instances of the same thing?"
-4. **Find the essence** — What's the same underneath all of them? What's incidental vs. fundamental?
-5. **Extract the abstraction** — What's the domain-independent pattern?
-6. **Test it** — Do all cases fit cleanly, without special-casing?
-7. **Measure the cascade** — Count: how many things become deletable?
-
-The discovery usually happens at step 3. Steps 4-7 are execution and validation.
-
-## The Net Deletion Test
-
-A real cascade reduces total code. If implementation requires significant new infrastructure, that may be a worthwhile trade — but it's not a cascade. Complexity moved is not complexity removed.
-
-Ask: "Did we delete more than we wrote?"
-
-## False Cascades: When Not to Simplify
-
-Not every unification is a simplification. The AHA principle (Avoid Hasty Abstractions) captures the failure mode: the wrong abstraction is worse than duplication.
-
-**Warning signs of a false cascade:**
-
-| Signal | What it means |
-|--------|--------------|
-| Callers need to know what's underneath to use it correctly | The abstraction leaks — you found the wrong level |
-| Special cases accumulate *around* the new abstraction | You haven't found the general case yet |
-| Net lines of code went *up* | This is a trade, not a cascade |
-| The abstraction is harder to explain than the concrete cases | Complexity moved, not removed |
-| Instances must be bent or coerced to fit | The abstraction precedes the pattern |
-
-**Joel Spolsky's addendum**: Even correct simplification cascades don't eliminate underlying complexity — they hide it most of the time. When the abstraction leaks (and eventually it will), you need to understand the layers. The cascade reduces cognitive load day-to-day; it doesn't eliminate the need to understand the substrate in edge cases.
-
-## Productive Tension: DRY vs. AHA
-
-These two principles aren't contradictions — they describe different moments in the same process:
-
-- **DRY / Rule of Three**: Once three instances exist, unify them
-- **AHA / YAGNI**: Don't abstract speculatively; prefer duplication over the wrong abstraction
-
-**The resolution**: Duplicate until the right abstraction reveals itself. Then unify. The cascade is the moment when the right abstraction becomes visible. Before that moment, the discipline is *waiting*.
-
-## Examples
-
-### Cascade 1: Stream Abstraction
-**Before:** Separate handlers for batch, real-time, file, and network data  
-**Insight:** "All inputs are streams — just different sources"  
-**After:** One stream processor, multiple stream adapters  
-**Deleted:** 4 separate implementations, 4 sets of tests, 4 maintenance burdens
-
-### Cascade 2: Resource Governance
-**Before:** Session tracking, rate limiting, file validation, connection pooling — all separate systems  
-**Insight:** "All are per-entity resource limits"  
-**After:** One `ResourceGovernor` with 4 resource types  
-**Deleted:** 4 custom enforcement systems and their interaction bugs
-
-### Cascade 3: Immutability
-**Before:** Defensive copying, locking, cache invalidation, temporal coupling — handled everywhere  
-**Insight:** "Treat everything as immutable data + transformations"  
-**After:** Functional patterns; state change = new value  
-**Deleted:** Entire classes of synchronization problems
-
-## Remember
-
-- Cascades are discovered, not designed — accumulate instances first
-- The test is net deletion: less total code, not just reorganized code
-- Complexity moved ≠ complexity removed
-- One powerful abstraction > ten clever hacks
-- The right unification usually feels obvious in retrospect

package/skills/problem-solving/simplification-cascades/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:problem-solving/simplification-cascades",
-    "title": "Simplification Cascades",
-    "aliases": [
-        "simplification-cascades",
-        "problem-solving/simplification-cascades"
-    ]
-}

package/skills/problem-solving/when-stuck/SKILL.md

@@ -1,69 +0,0 @@
----
-name: when-stuck
-description: Dispatch to the right problem-solving technique based on how you're stuck. Use this skill whenever you hit a wall — code behaving wrong, complexity spiraling, can't find a good approach, assumptions feel forced, unclear how it will scale, or you need to pick the right debugging technique before diving in. Use it proactively before major architecture decisions or when a solution feels like it's fighting you.
-metadata:
-  version: "2.0.0"
----
-
-# When Stuck — Problem-Solving Dispatch
-
-## Core Principle
-
-Different stuck-types need different techniques. Picking the wrong technique wastes time. This skill helps you identify the right one in under a minute.
-
-**Match symptom → technique, then load and follow that skill.**
-
-## Stuck-Type → Technique
-
-| How You're Stuck | Technique to Use |
-|------------------|-----------------|
-| **Complexity spiraling** — Same thing implemented 5+ ways, growing special cases, each fix reveals a new problem | `simplification-cascades` |
-| **Need innovation** — Conventional solutions feel inadequate, stuck inside one way of thinking, need breakthrough | `collision-zone-thinking` |
-| **Recurring patterns** — Same issue across different domains, reinventing wheels, déjà vu in problem-solving | `meta-pattern-recognition` |
-| **Forced by assumptions** — "Must be done this way," solution fights the system, can't question the premise | `inversion-exercise` |
-| **Scale uncertainty** — Unsure it'll hold at production, edge cases unclear, architecture decisions without load data | `scale-game` |
-| **Code broken** — Wrong behavior, test failing, unexpected output, bug with unknown root cause | `systematic-debugging` |
-| **Symptom clear, cause hidden** — Error is deep in the call chain, fix locations but not the origin | `root-cause-tracing` |
-| **Multiple independent problems** — Separate failing tests, parallel research questions, independent subsystems | `dispatching-parallel-agents` |
-| **Starting fresh, scope unclear** — New feature, unclear requirements, don't know what to build | `brainstorming` |
-| **Have a plan, need execution** — Know what to build, complex multi-step implementation ahead | `writing-plans` |
-
-## How to Identify Your Stuck-Type
-
-If the symptom isn't obvious, ask these questions:
-
-1. **Is something broken?** → `systematic-debugging` (always start here for bugs)
-2. **Is there too much code doing similar things?** → `simplification-cascades`
-3. **Does the solution feel forced or fight the codebase?** → `inversion-exercise`
-4. **Does nothing in this domain work?** → `collision-zone-thinking` (leave the domain)
-5. **Have I seen this shape before in other contexts?** → `meta-pattern-recognition`
-6. **Do I not know if it'll hold under load?** → `scale-game`
-7. **Is the problem actually several independent things?** → `dispatching-parallel-agents`
-
-## Proactive Use (Not Just When Stuck)
-
-Some techniques should be used *before* you're stuck:
-
-- **Before major architecture decisions** → `inversion-exercise` (pre-mortem: "how would this fail?")
-- **Before implementing a complex feature** → `brainstorming` then `writing-plans`
-- **Before committing to a design at scale** → `scale-game`
-- **When a config file or handler list keeps growing** → `simplification-cascades`
-
-## Combining Techniques
-
-Some problems need more than one:
-
-| Combination | When to Use |
-|-------------|-------------|
-| `systematic-debugging` → `root-cause-tracing` | Bug found, but fix location is far from origin |
-| `simplification-cascades` + `meta-pattern-recognition` | Find the recurring pattern, then collapse all instances |
-| `collision-zone-thinking` + `inversion-exercise` | Force a new metaphor, then stress-test its assumptions |
-| `scale-game` + `simplification-cascades` | Extremes reveal what to eliminate |
-| `inversion-exercise` + `scale-game` | "How does this fail?" × "At what scale?" |
-
-## If Still Stuck After First Technique
-
-1. Try a different technique from the table — wrong diagnosis is common
-2. Combine two techniques (see above)
-3. If 3+ fixes have failed for a bug → this is an architectural problem, not a debugging problem. Use `inversion-exercise` to question the design.
-4. Step back: is the problem statement itself wrong? → `brainstorming`

package/skills/problem-solving/when-stuck/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:problem-solving/when-stuck",
-    "title": "When Stuck - Problem-Solving Dispatch",
-    "aliases": [
-        "when-stuck",
-        "problem-solving/when-stuck"
-    ]
-}

package/skills/research/ABOUT.md

@@ -1,20 +0,0 @@
-# Research Skills - Attribution
-
-This skill was derived from agent patterns in the [Amplifier](https://github.com/microsoft/amplifier) project.
-
-**Source Repository:**
-- Name: Amplifier
-- URL: https://github.com/microsoft/amplifier
-- Commit: 2adb63f858e7d760e188197c8e8d4c1ef721e2a6
-- Date: 2025-10-10
-
-## Skills Derived from Amplifier Agents
-
-**From knowledge-archaeologist agent:**
-- tracing-knowledge-lineages - Understanding how ideas evolved over time to find old solutions for new problems and avoid repeating past failures
-
-## What Was Adapted
-
-The knowledge-archaeologist agent excels at temporal analysis of knowledge evolution, paradigm shift documentation, and preserving the "fossil record" of ideas. This skill extracts the core research techniques for understanding why current approaches exist before proposing changes.
-
-Adapted with practical search strategies (decision records, git archaeology, conversation history) and scoped for mature codebases (explicitly notes to skip for greenfield projects).