mathias
08c935ba8a
superpowers-systematic-debugging restated debug's core (hypothesis before fix) across 296 lines, with a fix-implementation phase that belongs to tdd and a rationalization table that mostly repeats debug's own Anti-Patterns. Two things in it were not restatement, and both are now in debug: instrument every component boundary before hypothesising when a bug spans components, and treat three failed fixes as evidence the mechanism was never identified rather than as a reason to try a fourth. Not deleted with it, contrary to the issue: find-polluter.sh and the three technique files (root-cause-tracing, defense-in-depth, condition-based-waiting) are real assets, one of them an actual tool. They move to debug/references/ with a stated load trigger each, because a reference nobody knows when to open is dead weight. The pressure-test transcripts and CREATION-LOG from the upstream fork go; they document obra's process, not ours. Pressure-tested per #19, and the RED phase refuted the issue's premise. Two subagents without the skill got the multi-component scenario and the four-failed- fixes scenario; both already instrumented boundaries unprompted, and the second refused to write a fifth fix on its own initiative. So these sections are not correcting a demonstrated gap in this model — they are insurance for weaker models and for prompts less well-posed than a test scenario. Recorded as such rather than claimed as a fix. The GREEN run applied both sections correctly and then found four defects in them, all fixed here: the boundary rule read as suspending Iron Law 2's 3-5 hypotheses; the trigger said "reduced" when fixes that change nothing are the stronger signal; "stop proposing a fourth" read as licence to return no hypotheses at all; and the references had no load triggers. Its remaining findings are pre-existing and filed as #36. 41 skills. debug 146 -> 188 lines. Closes #14 Bump-Type: minor
3.4 KiB
3.4 KiB
Condition-Based Waiting
Overview
Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines 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
digraph when_to_use {
"Test uses setTimeout/sleep?" [shape=diamond];
"Testing timing behavior?" [shape=diamond];
"Document WHY timeout needed" [shape=box];
"Use condition-based waiting" [shape=box];
"Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
"Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
"Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
}
Use when:
- Tests have arbitrary delays (
setTimeout,sleep,time.sleep()) - Tests are flaky (pass sometimes, fail under load)
- Tests timeout when run in parallel
- Waiting for async operations to complete
Don't use when:
- Testing actual timing behavior (debounce, throttle intervals)
- Always document WHY if using arbitrary timeout
Core Pattern
// ❌ BEFORE: Guessing at timing
await new Promise(r => setTimeout(r, 50));
const result = getResult();
expect(result).toBeDefined();
// ✅ AFTER: Waiting for condition
await waitFor(() => getResult() !== undefined);
const result = getResult();
expect(result).toBeDefined();
Quick Patterns
| Scenario | Pattern |
|---|---|
| Wait for event | waitFor(() => events.find(e => e.type === 'DONE')) |
| Wait for state | waitFor(() => machine.state === 'ready') |
| Wait for count | waitFor(() => items.length >= 5) |
| Wait for file | waitFor(() => fs.existsSync(path)) |
| Complex condition | waitFor(() => obj.ready && obj.value > 10) |
Implementation
Generic polling function:
async function waitFor<T>(
condition: () => T | undefined | null | false,
description: string,
timeoutMs = 5000
): Promise<T> {
const startTime = Date.now();
while (true) {
const result = condition();
if (result) return result;
if (Date.now() - startTime > timeoutMs) {
throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
}
await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
}
}
See condition-based-waiting-example.ts in this directory for complete implementation with domain-specific helpers (waitForEvent, waitForEventCount, waitForEventMatch) from actual debugging session.
Common Mistakes
❌ Polling too fast: setTimeout(check, 1) - wastes CPU
✅ Fix: Poll every 10ms
❌ No timeout: Loop forever if condition never met ✅ Fix: Always include timeout with clear error
❌ Stale data: Cache state before loop ✅ Fix: Call getter inside loop for fresh data
When Arbitrary Timeout IS Correct
// Tool ticks every 100ms - need 2 ticks to verify partial output
await waitForEvent(manager, 'TOOL_STARTED'); // First: wait for condition
await new Promise(r => setTimeout(r, 200)); // Then: wait for timed behavior
// 200ms = 2 ticks at 100ms intervals - documented and justified
Requirements:
- First wait for triggering condition
- Based on known timing (not guessing)
- Comment explaining WHY
Real-World Impact
From debugging session (2025-10-03):
- Fixed 15 flaky tests across 3 files
- Pass rate: 60% → 100%
- Execution time: 40% faster
- No more race conditions