@complexthings/superpowers-agent 9.2.1 → 10.0.1

package/skills/research/tracing-knowledge-lineages/SKILL.md

@@ -1,241 +0,0 @@
----
-name: tracing-knowledge-lineages
-description: "Trace the historical lineage of technical ideas, patterns, and architectures to rediscover proven solutions, understand WHY current approaches exist, and avoid repeating failures. Use when you encounter 'why do we do it this way?', 'is this a new problem?', 'what has been tried before?', 'has this pattern emerged before?', or when designing systems that resemble something from the past."
-metadata:
-  category: research
-  version: 1.2.0
----
-
-# Tracing Knowledge Lineages
-
-## Why This Matters
-
-Every technical decision carries invisible weight from the past. When you skip lineage tracing:
-
-- You reinvent failed approaches because you don't know they failed
-- You miss proven patterns that already solved your exact problem
-- You don't understand WHY the current approach exists, so you can't safely deviate from it
-- You create architecture that repeats historical mistakes your predecessors already paid for
-
-The goal isn't to be constrained by history — it's to be *informed* by it. Knowing the lineage lets you deviate deliberately rather than ignorantly.
-
-## When to Trace Lineages
-
-**Always trace when:**
-- You're designing something and someone says "isn't this like X?"
-- You're questioning why something is done a certain way
-- You're proposing to remove or replace an established pattern
-- You're encountering a problem that "feels old"
-- You're evaluating a technology that claims to be new
-
-**Quick trace (5 minutes):** Is this pattern familiar? → Search for historical names → Find 2–3 examples → Note outcomes
-
-**Deep trace (30+ minutes):** Before architectural decisions, major refactors, or when the quick trace surfaces surprising history
-
----
-
-## The Four Core Techniques
-
-### 1. Decision Archaeology
-
-Excavate the reasoning behind existing choices — not just what was decided, but why, and what alternatives were rejected.
-
-**Sources to mine:**
-- `git log --all --grep="why\|decision\|chose\|considered\|rejected"` — look for commit messages explaining reasoning
-- Architecture Decision Records (ADRs), RFCs, and design docs in `/docs`, `/adr`, `/rfcs`
-- Ticket trackers (JIRA, Linear, GitHub Issues) — search for the feature name + "alternative" or "rejected"
-- Team Slack/Discord history — search around the dates of significant commits
-- PR descriptions and review comments: `git log --merges --format="%H %s" | head -50`, then check PRs
-
-**What to capture:**
-- The alternatives that were *considered but rejected* — these are as valuable as what was chosen
-- The constraints that shaped the decision (team size, deadline, scale, tooling available then)
-- Whether those constraints still apply today
-
-**Probe questions:**
-> "What problem was this solving when it was introduced?"
-> "What was the runner-up solution, and why was it rejected?"
-> "What has changed since this decision was made?"
-
----
-
-### 2. Failed Attempt Analysis
-
-Failures are the most valuable and most hidden part of technical history. They rarely get documented, but they repeat.
-
-**Finding hidden failures:**
-- Reverted commits: `git log --all --diff-filter=R` or search for "revert" in commit history
-- Short-lived branches: `git branch -r | xargs -I{} git log --oneline -1 {}` — branches that were created and abandoned
-- Half-migrated code: look for dual implementations (old + new living side by side)
-- "TODO: remove this once X" comments that were never removed
-- Changelog entries that disappeared in later versions
-
-**The failure taxonomy:**
-| Type | Signal | What to learn |
-|------|--------|---------------|
-| Performance failure | Reverted optimization, "too slow" in commits | What the scale thresholds were |
-| Complexity failure | "Simplified", "removed abstraction" | Where the abstraction broke down |
-| Adoption failure | Feature removed, flag disabled | What made it hard to use |
-| Timing failure | "Premature", "not ready" | What prerequisites were missing |
-
----
-
-### 3. Revival Detection
-
-Old patterns resurface under new names. Recognizing revivals lets you access 30+ years of operational experience immediately.
-
-**Technically accurate revival lineages:**
-
-| Modern Pattern | Historical Ancestor | What the revival added |
-|---------------|--------------------|-----------------------|
-| Serverless Functions | Time-sharing systems (1960s) + Unix daemons | Elastic billing, managed infra |
-| GraphQL | SGML/XQL query languages + SOAP/WSDL | Typed schema, client-driven queries |
-| NoSQL Document Stores | IMS hierarchical DB + CODASYL network DBs (1970s) | Horizontal scale, flexible schema |
-| Microservices | CORBA/SOA (1990s–2000s) | Lightweight protocols, containers |
-| Edge Computing | CDN + Akamai ESI (early 2000s) | Full compute, not just caching |
-| Server Components (React) | Server-side rendering + JSP/PHP | Component model + streaming |
-| Event Sourcing | Append-only ledgers + audit logs | Projections, temporal queries |
-| Infrastructure as Code | LISP machine system images + Puppet/Chef | Declarative, version-controlled |
-
-**Revival research steps:**
-1. Name the modern pattern precisely
-2. Ask: "what did this replace, and what did the replacement itself replace?"
-3. Search: `[pattern name] history site:lobste.rs OR site:news.ycombinator.com`
-4. Look for talks titled "X considered harmful" or "the return of Y"
-
----
-
-### 4. Paradigm Shift Mapping
-
-Understand what changed — constraints, tooling, scale, understanding — that made old approaches viable again or newly obsolete.
-
-**The shift template:**
-```
-Old constraint: [what made X unworkable before]
-New condition: [what changed]
-Therefore: [why X is viable/necessary now]
-```
-
-**Example:**
-```
-Old constraint: RAM was expensive; storing state in memory meant high cost
-New condition: RAM is effectively free at the scale most apps run
-Therefore: In-memory state machines (XState, Zustand) beat complex DB state management
-```
-
-**Constraint categories to check:**
-- **Cost**: storage, compute, bandwidth costs have changed dramatically
-- **Speed**: network latency, CPU speed, disk I/O profiles
-- **Scale**: how many users, requests, data volume
-- **Tooling**: what primitives are now available (containers, managed databases, type systems)
-- **Team**: what skills are now common vs. rare
-
----
-
-## Search Strategy
-
-### Code & Version Control
-```bash
-# Commits explaining reasoning
-git log --all --grep="because\|reason\|trade-off\|instead of\|considered"
-
-# Reverted changes (hidden failures)
-git log --all --grep="[Rr]evert" --oneline
-
-# Find old implementations
-git log --all --full-history -- "**/old-*" "**/deprecated-*" "**/legacy-*"
-
-# When was this pattern introduced?
-git log -S "pattern_name" --oneline
-```
-
-### Documentation & Issues
-- GitHub/GitLab: search `repo:org/name "why" OR "reason" OR "considered"`  
-- JIRA/Linear: filter by date range around when the pattern was introduced  
-- Confluence/Notion: search for the component name + "decision" or "RFC"
-
-### Web Archaeology
-- `site:news.ycombinator.com "[technology name]"` — HN discussions often contain expert history
-- `site:lobste.rs "[technology name]"` — deeper technical discussions
-- ACM Digital Library / IEEE Xplore for academic lineage
-- The Wayback Machine for documentation of dead projects
-- Wikipedia revision history for contested technical decisions
-
----
-
-## Recognizing Lineage Signals
-
-**In code:**
-- Comments starting with "NB:", "NOTE:", "FIXME:", "HACK:", "WARNING:" — often explain constraints
-- Unusually defensive code in an otherwise simple module
-- Abstraction layers that wrap a single thing
-- Feature flags that have been "temporary" for years
-
-**In conversations:**
-- "We tried that before" — ALWAYS follow up: "What happened?"
-- "That won't work here" — ask for the specific failure scenario
-- "We have reasons" — that phrase usually means there's archaeology to do
-
-**In architecture:**
-- Two implementations of the same thing existing simultaneously
-- Naming like `*_v2`, `*_new`, `*_refactored`
-- Explicit "Do Not Use" warnings pointing to another implementation
-
----
-
-## Synthesizing Your Findings
-
-A lineage trace is only valuable if it produces actionable insight. Structure your output:
-
-```markdown
-## Lineage: [Pattern/Decision Name]
-
-**What it is now:** [one sentence]
-
-**Historical origin:** [oldest known ancestor + approximate era]
-
-**Key evolution steps:**
-1. [era] — [what existed and what problem it solved]
-2. [era] — [what changed and why]
-3. [current] — [how we got here]
-
-**Failed attempts along the way:**
-- [attempt] failed because [reason] — still relevant because [implication]
-
-**What the history tells us:**
-- The core problem being solved is [X], not [Y]
-- This approach works when [conditions]; breaks when [other conditions]
-- The constraint that shaped this was [Z] — that constraint [still applies / no longer applies]
-
-**Implication for current work:**
-[One concrete decision or caution derived from the lineage]
-```
-
----
-
-## Informed Deviation: Using History to Break from It
-
-Knowing the lineage doesn't mean being constrained by it — it means you can break from it *deliberately*. Before deviating from an established pattern:
-
-1. **Name the constraint that shaped the original decision**
-   - "This was built when we had X constraint"
-2. **Verify whether that constraint still applies**
-   - "That constraint no longer applies because Y"
-3. **Check if the deviation was tried before**
-   - "This exact deviation was tried in [branch/ticket/year] and failed because Z"
-4. **State your deviation explicitly**
-   - "We are intentionally deviating from the historical pattern because [conditions changed]"
-
-The trap to avoid: "We don't need to do it that way anymore" without knowing *why* it was done that way in the first place.
-
----
-
-## Anti-Patterns
-
-| Anti-pattern | What it looks like | The fix |
-|---|---|---|
-| **Present bias** | "That's old, we don't need to learn from it" | Old failures are especially relevant — same problems, different names |
-| **Success bias** | Only tracing the winning path | Failed attempts teach more than successes |
-| **Shallow attribution** | "This is like X" without understanding WHY | Trace through to first principles |
-| **Archive paralysis** | Spending days on lineage for a one-day task | Time-box: quick trace = 5 min, deep trace = 30 min |
-| **Context stripping** | "They tried X and it failed" without the why | Always capture the conditions under which it failed |

package/skills/research/tracing-knowledge-lineages/skill.json

@@ -1,9 +0,0 @@
-{
-    "version": "1.1.0",
-    "name": "superpowers:research/tracing-knowledge-lineages",
-    "title": "Tracing Knowledge Lineages",
-    "aliases": [
-        "tracing-knowledge-lineages",
-        "research/tracing-knowledge-lineages"
-    ]
-}

package/skills/testing/condition-based-waiting/SKILL.md

@@ -1,359 +0,0 @@
----
-name: condition-based-waiting
-description: Replace arbitrary timeouts with condition polling for reliable async tests. Use this skill whenever you see setTimeout/sleep/time.sleep in tests, tests are flaky or inconsistent across machines or CI, tests timeout under parallel load, or you're waiting for async operations like events, state changes, DOM updates, file writes, or API responses. Also use when debugging race conditions, investigating "why does this test sometimes fail", or looking for test speed improvements by removing unnecessary waits.
-metadata:
-  version: 2.1.0
-  languages: all
----
-
-# Condition-Based Waiting
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on a fast dev machine but fail under load or in CI.
-
-**Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
-
-## When to Use
-
-```
-Test uses setTimeout/sleep?
-  └─ Testing actual timing behavior? (debounce, throttle, tick intervals)
-       ├─ YES → Document WHY the timeout is needed (see "When Arbitrary Timeout IS Correct")
-       └─ NO  → Replace with condition-based waiting
-                  └─ System emits events? → Prefer event-based waiting (fastest, no polling)
-                     Otherwise           → Use condition polling
-```
-
-**Use when:**
-- Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
-- Tests are flaky (pass sometimes, fail under load or in CI)
-- Tests timeout when run in parallel
-- Waiting for: async operations, DOM updates, state changes, file writes, queue drains
-
-**Don't use when:**
-- Testing actual timing behavior (debounce delay, throttle interval, tick frequency)
-- Your test framework already has built-in auto-waiting (Playwright, Cypress) — use those instead
-- Always document WHY when keeping an arbitrary timeout
-
-## Decision: Poll vs Event
-
-| Approach | Use when | Latency | CPU |
-|----------|----------|---------|-----|
-| Event listener | System emits events/promises | ~0ms | Zero |
-| Framework built-ins | Playwright, Cypress, Testing Library | ~0ms | Zero |
-| Polling | System has no observable events | 0–50ms | Low |
-
-**Event-based (zero latency, preferred when possible):**
-```typescript
-// ✅ If system emits events, listen instead of polling
-async function waitForEvent<T>(emitter: EventEmitter, event: string, timeoutMs = 5000): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      emitter.removeListener(event, resolve);
-      reject(new Error(`Timeout waiting for "${event}" event after ${timeoutMs}ms`));
-    }, timeoutMs);
-    emitter.once(event, (data: T) => { clearTimeout(timer); resolve(data); });
-  });
-}
-```
-
-**Polling (when no events available):**
-```typescript
-// ✅ Poll at 50ms — responsive without hammering the CPU
-await waitFor(() => system.isReady(), 'system to be ready');
-```
-
-## Core Pattern
-
-```typescript
-// ❌ BEFORE: Guessing at timing
-await new Promise(r => setTimeout(r, 300));
-const result = getResult();
-expect(result).toBeDefined();
-
-// ✅ AFTER: Waiting for condition
-await waitFor(() => getResult() !== undefined, 'result to be defined');
-const result = getResult();
-expect(result).toBeDefined();
-```
-
-## Quick Patterns
-
-| Scenario | Pattern |
-|----------|---------|
-| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'), 'DONE event')` |
-| Wait for state | `waitFor(() => machine.state === 'ready' && machine.state, 'ready state')` |
-| Wait for count | `waitFor(() => items.length >= 5 && items, '5+ items')` |
-| Wait for file | `waitFor(() => fs.existsSync(path) && path, 'file to exist')` |
-| Wait for disappearance | `waitFor(() => !getElement() || true, 'element removed')` |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10 && obj, 'obj ready')` |
-
-> **Note:** The condition must return a truthy value to resolve — returning `false`, `null`, `undefined`, or `0` triggers another poll.
-
-## Generic Implementation (TypeScript)
-
-```typescript
-async function waitFor<T>(
-  condition: () => T | undefined | null | false,
-  description: string,
-  timeoutMs = 5000,
-  intervalMs = 50  // 50ms matches Testing Library's default — fast enough, CPU-friendly
-): Promise<T> {
-  const startTime = Date.now();
-
-  while (true) {
-    const result = condition();
-    if (result) return result as T;
-
-    const elapsed = Date.now() - startTime;
-    if (elapsed > timeoutMs) {
-      // Include current state in error — saves a debugging round-trip
-      const current = (() => { try { return condition(); } catch { return 'error evaluating'; } })();
-      throw new Error(
-        `Timeout waiting for "${description}" after ${timeoutMs}ms. Current value: ${JSON.stringify(current)}`
-      );
-    }
-
-    await new Promise(r => setTimeout(r, intervalMs));
-  }
-}
-```
-
-See `example.ts` for domain-specific helper implementations (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`).
-
-## Throw-Based vs Falsy-Return Retry
-
-Two valid retry styles — choose based on context:
-
-**Falsy-return** (above implementation — simple boolean conditions):
-```typescript
-// Retries while condition returns falsy
-await waitFor(() => queue.length > 0 && queue, 'queue to have items');
-```
-
-**Throw-based** (Testing Library style — assertions as conditions):
-```typescript
-// Retries while callback throws; stops when it doesn't throw
-await waitFor(() => {
-  expect(getItems()).toHaveLength(3); // throws until length === 3
-});
-```
-
-Use throw-based when wrapping `expect()` assertions. Use falsy-return for plain boolean/value conditions. Don't mix the two styles in the same `waitFor` call.
-
-## ⚠️ Fake Timer Incompatibility (Critical Pitfall)
-
-The `setTimeout(r, interval)` inside `waitFor` **never fires** when Jest/Vitest fake timers are active:
-
-```typescript
-// ❌ This hangs forever — fake timers swallow the setTimeout inside waitFor
-vi.useFakeTimers();
-await waitFor(() => store.isReady(), 'store ready'); // deadlock
-```
-
-**Fix option 1 — Flush pending timers before restoring real timers (recommended):**
-```typescript
-afterEach(() => {
-  jest.runOnlyPendingTimers(); // flush 3rd-party timers before switching
-  jest.useRealTimers();
-});
-```
-
-**Fix option 2 — Advance fake timers to cover polling intervals:**
-```typescript
-vi.useFakeTimers();
-const waiting = waitFor(() => store.isReady(), 'store ready');
-vi.advanceTimersByTime(5000); // advance past all polling intervals
-await waiting;
-```
-
-**Fix option 3 — Switch to real timers for the wait:**
-```typescript
-vi.useFakeTimers();
-// ... trigger work with fake timers ...
-vi.useRealTimers();
-await waitFor(() => store.isReady(), 'store ready');
-vi.useFakeTimers(); // restore if needed
-```
-
-**Fix option 4 — Skip `waitFor` entirely (when feasible):**
-```typescript
-// If condition can be checked synchronously after advancing timers:
-vi.useFakeTimers();
-vi.runAllTimers(); // flush all pending fake timers
-expect(store.isReady()).toBe(true); // direct check, no waitFor needed
-```
-
-**Rule:** If your test uses fake timers, you cannot use `setTimeout`-based polling without explicitly advancing time.
-
-## Framework Built-Ins (Use These First)
-
-If you're already using one of these frameworks, use their built-in waiting — don't reinvent the wheel:
-
-### Testing Library (`@testing-library/react`, etc.)
-
-```typescript
-import { waitFor, waitForElementToBeRemoved, screen } from '@testing-library/react';
-
-// waitFor: poll until assertion passes (retries when callback THROWS)
-await waitFor(() => expect(screen.getByText('Done')).toBeVisible());
-// Defaults: timeout=1000ms, interval=50ms
-
-// findBy* = getBy* + waitFor (most common pattern)
-const button = await screen.findByRole('button', { name: 'Submit' });
-await screen.findByText('Loaded', {}, { timeout: 2000 });
-
-// waitForElementToBeRemoved: wait for disappearance
-await waitForElementToBeRemoved(() => screen.queryByText('Loading...'));
-```
-
-**Critical:** Testing Library's `waitFor` retries when the callback **throws** — not when it returns falsy. Always use `expect(...)` assertions inside, not boolean returns.
-
-### Playwright (auto-waits on every action)
-
-```typescript
-// ✅ Actions auto-wait (visible + stable + enabled + receives events):
-await page.click('button#submit');
-await page.fill('input[name=email]', 'test@example.com');
-
-// ✅ Assertions auto-retry until timeout:
-await expect(page.locator('.status')).toHaveText('Ready');
-await expect(page.locator('.spinner')).toBeHidden();
-await expect(page).toHaveURL('/dashboard');
-
-// ✅ Explicit element state wait:
-await page.locator('.spinner').waitFor({ state: 'hidden' });
-
-// ✅ Custom condition evaluated in browser JS:
-await page.waitForFunction(() => window.__appReady === true);
-```
-
-Manual polling is rarely needed in Playwright — auto-wait handles the common cases.
-
-### Cypress (retry-ability built into query chains)
-
-```javascript
-// ✅ .get() + .should() retries the chain automatically
-cy.get('.status').should('have.text', 'Ready');
-cy.get('@mySpy').should('have.been.calledOnce');
-
-// ✅ For explicit polling:
-cy.waitUntil(() => cy.window().then(w => w.store?.initialized));
-```
-
-## Cross-Language Patterns
-
-### Python (pytest-asyncio)
-
-```python
-import asyncio
-
-async def wait_for_condition(condition_fn, description, timeout=5.0, interval=0.05):
-    """Poll until condition_fn() returns truthy or timeout expires."""
-    deadline = asyncio.get_event_loop().time() + timeout
-    while asyncio.get_event_loop().time() < deadline:
-        if condition_fn():
-            return
-        await asyncio.sleep(interval)
-    current = condition_fn()
-    raise TimeoutError(
-        f'Timeout waiting for "{description}" after {timeout}s. Current: {current!r}'
-    )
-
-@pytest.mark.asyncio
-async def test_queue_drains():
-    items = list(range(10))
-    asyncio.get_event_loop().call_later(0.1, items.clear)
-    await wait_for_condition(lambda: len(items) == 0, 'queue to drain')
-    assert items == []
-```
-
-> **Pitfall:** Call the getter *inside* the loop — never cache state before entering the loop or you'll check a stale snapshot.
-
-### Go
-
-```go
-// stdlib — good for goroutine synchronization
-func TestWorkerFinishes(t *testing.T) {
-    done := make(chan struct{})
-    go func() { time.Sleep(50 * time.Millisecond); close(done) }()
-
-    select {
-    case <-done:
-        // success
-    case <-time.After(2 * time.Second):
-        t.Fatal("worker did not finish within 2s")
-    }
-}
-
-// testify — good for polling arbitrary conditions
-require.Eventually(t,
-    func() bool { return cache.Has("users") },
-    2*time.Second,       // total timeout
-    10*time.Millisecond, // poll interval
-    "cache never populated 'users' key",
-)
-```
-
-> **Pitfall (gomega/testify):** Pass a *getter function* — not a value. `Eventually(cache.Has("users"), ...)` snapshots once; `Eventually(func() bool { return cache.Has("users") }, ...)` re-evaluates live.
-
-### Rust (tokio)
-
-```rust
-use std::sync::{Arc, Mutex};
-use tokio::time::{sleep, timeout, Duration};
-
-#[tokio::test]
-async fn test_flag_set_by_background_task() {
-    let flag = Arc::new(Mutex::new(false));
-    let flag_clone = Arc::clone(&flag);
-    tokio::spawn(async move {
-        sleep(Duration::from_millis(100)).await;
-        *flag_clone.lock().unwrap() = true;
-    });
-
-    timeout(Duration::from_secs(2), async {
-        loop {
-            if *flag.lock().unwrap() { break; }
-            sleep(Duration::from_millis(50)).await; // use sleep, not yield_now
-        }
-    }).await.expect("flag was never set within 2s");
-}
-```
-
-> **Pitfall:** Use `sleep()`, not `yield_now()`, in test polling loops — `yield_now` starves other tasks on the single-threaded test runtime.
-
-## Common Mistakes
-
-| Mistake | Fix |
-|---------|-----|
-| `setTimeout(check, 1)` — polls too fast | Use 50ms; sub-10ms wastes CPU with no benefit |
-| No timeout — loops forever | Always include timeout with descriptive error |
-| Check stale data — cached before loop | Call getter *inside* loop for fresh data |
-| Vague timeout error — "condition not met" | Include current state: `Current value: ${JSON.stringify(val)}` |
-| Returning falsy from Testing Library `waitFor` | Throw inside `waitFor` — use `expect()` assertions |
-| `waitFor` under fake timers — hangs | See [Fake Timer Incompatibility] above |
-
-## When Arbitrary Timeout IS Correct
-
-Some behavior is inherently time-based. The pattern: wait for condition first, then wait for timed behavior:
-
-```typescript
-// Tool ticks every 100ms — need 2 ticks to verify partial output
-await waitForEvent('TOOL_STARTED');            // 1. Wait for triggering condition
-await new Promise(r => setTimeout(r, 200));    // 2. Wait for known timing behavior
-// 200ms = 2 ticks at 100ms intervals — documented and justified
-```
-
-**Requirements for a legitimate arbitrary timeout:**
-1. First wait for the triggering condition (don't skip this)
-2. Duration based on known timing (e.g., "this runs every 100ms") — not a guess
-3. Comment explains WHY the specific duration was chosen
-
-## Real-World Impact
-
-From a debugging session replacing 15 arbitrary timeouts across 3 test files:
-- Pass rate: **60% → 100%** (eliminated race conditions)
-- Execution time: **40% faster** (no more waiting out unnecessary delays)
-- Zero flaky failures in CI after the change