@ctxthuta/cxops 1.0.7 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/.antigravity-plugin/plugin.json +34 -0
  2. package/.claude-plugin/marketplace.json +20 -0
  3. package/.claude-plugin/plugin.json +25 -0
  4. package/.codex-plugin/plugin.json +50 -0
  5. package/CLAUDE.md +16 -1
  6. package/assets/antigravity-logo.png +0 -0
  7. package/assets/app-icon.png +0 -0
  8. package/assets/superpowers-small.svg +1 -0
  9. package/hooks/hooks-cursor.json +10 -0
  10. package/hooks/hooks.json +18 -0
  11. package/hooks/run-hook.cmd +79 -0
  12. package/hooks/session-start +90 -0
  13. package/package.json +12 -2
  14. package/plugin/plugin.json +25 -14
  15. package/plugin/skills/brainstorming/SKILL.md +316 -0
  16. package/plugin/skills/brainstorming/builder-check-prompt.md +23 -0
  17. package/plugin/skills/brainstorming/scripts/frame-template.html +213 -0
  18. package/plugin/skills/brainstorming/scripts/helper.js +167 -0
  19. package/plugin/skills/brainstorming/scripts/server.cjs +723 -0
  20. package/plugin/skills/brainstorming/scripts/start-server.sh +216 -0
  21. package/plugin/skills/brainstorming/scripts/stop-server.sh +120 -0
  22. package/plugin/skills/brainstorming/visual-companion.md +299 -0
  23. package/plugin/skills/diagnosing-superpowers/SKILL.md +120 -0
  24. package/plugin/skills/diagnosing-superpowers/prompts/analyst-common.md +38 -0
  25. package/plugin/skills/diagnosing-superpowers/prompts/cost-and-time.md +28 -0
  26. package/plugin/skills/diagnosing-superpowers/prompts/plan-adherence.md +29 -0
  27. package/plugin/skills/diagnosing-superpowers/prompts/quality-evidence.md +26 -0
  28. package/plugin/skills/diagnosing-superpowers/prompts/repeated-work.md +30 -0
  29. package/plugin/skills/diagnosing-superpowers/prompts/request-conflicts.md +20 -0
  30. package/plugin/skills/diagnosing-superpowers/prompts/scrub-audit.md +33 -0
  31. package/plugin/skills/diagnosing-superpowers/prompts/scrub.md +29 -0
  32. package/plugin/skills/diagnosing-superpowers/prompts/similar-session.md +38 -0
  33. package/plugin/skills/diagnosing-superpowers/prompts/skill-timeline.md +30 -0
  34. package/plugin/skills/diagnosing-superpowers/prompts/stumbles.md +28 -0
  35. package/plugin/skills/diagnosing-superpowers/references/context-safety.md +22 -0
  36. package/plugin/skills/diagnosing-superpowers/references/github-issues.md +47 -0
  37. package/plugin/skills/diagnosing-superpowers/references/redaction-policy.md +34 -0
  38. package/plugin/skills/diagnosing-superpowers/references/session-discovery.md +31 -0
  39. package/plugin/skills/diagnosing-superpowers/templates/bundle-README.md +77 -0
  40. package/plugin/skills/diagnosing-superpowers/templates/case.md +64 -0
  41. package/plugin/skills/diagnosing-superpowers/templates/issue.md +70 -0
  42. package/plugin/skills/diagnosing-superpowers/templates/report.md +82 -0
  43. package/plugin/skills/dispatching-parallel-agents/SKILL.md +167 -0
  44. package/plugin/skills/executing-plans/SKILL.md +323 -0
  45. package/plugin/skills/executing-plans/scripts/task-done +55 -0
  46. package/plugin/skills/executing-plans/scripts/task-start +32 -0
  47. package/plugin/skills/finishing-a-development-branch/SKILL.md +225 -0
  48. package/plugin/skills/receiving-code-review/SKILL.md +205 -0
  49. package/plugin/skills/requesting-code-review/SKILL.md +95 -0
  50. package/plugin/skills/requesting-code-review/code-reviewer.md +198 -0
  51. package/plugin/skills/subagent-driven-development/SKILL.md +339 -0
  52. package/plugin/skills/subagent-driven-development/implementer-prompt.md +154 -0
  53. package/plugin/skills/subagent-driven-development/re-review-prompt.md +116 -0
  54. package/plugin/skills/subagent-driven-development/references/batching.md +11 -0
  55. package/plugin/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  56. package/plugin/skills/subagent-driven-development/references/final-review.md +49 -0
  57. package/plugin/skills/subagent-driven-development/references/fix-loop.md +77 -0
  58. package/plugin/skills/subagent-driven-development/references/handling-reports.md +15 -0
  59. package/plugin/skills/subagent-driven-development/references/preflight.md +26 -0
  60. package/plugin/skills/subagent-driven-development/references/resuming.md +12 -0
  61. package/plugin/skills/subagent-driven-development/scripts/review-package +64 -0
  62. package/plugin/skills/subagent-driven-development/scripts/sdd-repo +54 -0
  63. package/plugin/skills/subagent-driven-development/scripts/sdd-workspace +110 -0
  64. package/plugin/skills/subagent-driven-development/scripts/task-brief +108 -0
  65. package/plugin/skills/subagent-driven-development/task-reviewer-prompt.md +209 -0
  66. package/plugin/skills/systematic-debugging/SKILL.md +283 -0
  67. package/plugin/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  68. package/plugin/skills/systematic-debugging/condition-based-waiting.md +115 -0
  69. package/plugin/skills/systematic-debugging/defense-in-depth.md +122 -0
  70. package/plugin/skills/systematic-debugging/find-polluter.sh +72 -0
  71. package/plugin/skills/systematic-debugging/root-cause-tracing.md +169 -0
  72. package/plugin/skills/test-driven-development/SKILL.md +330 -0
  73. package/plugin/skills/test-driven-development/writing-good-tests.md +198 -0
  74. package/plugin/skills/using-git-worktrees/SKILL.md +167 -0
  75. package/plugin/skills/using-superpowers/SKILL.md +65 -0
  76. package/plugin/skills/using-superpowers/references/antigravity-tools.md +23 -0
  77. package/plugin/skills/using-superpowers/references/claude-code-tools.md +29 -0
  78. package/plugin/skills/using-superpowers/references/codex-tools.md +108 -0
  79. package/plugin/skills/using-superpowers/references/gemini-tools.md +63 -0
  80. package/plugin/skills/using-superpowers/references/hermes-tools.md +56 -0
  81. package/plugin/skills/using-superpowers/references/muse-tools.md +35 -0
  82. package/plugin/skills/using-superpowers/references/pi-tools.md +16 -0
  83. package/plugin/skills/verification-before-completion/SKILL.md +120 -0
  84. package/plugin/skills/writing-plans/SKILL.md +204 -0
  85. package/plugin/skills/writing-skills/SKILL.md +399 -0
  86. package/plugin/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  87. package/plugin/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  88. package/plugin/skills/writing-skills/references/bulletproofing.md +80 -0
  89. package/plugin/skills/writing-skills/references/discovery.md +201 -0
  90. package/plugin/skills/writing-skills/references/flowcharts.md +37 -0
  91. package/plugin/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  92. package/plugin/skills/writing-skills/references/persuasion-principles.md +187 -0
  93. package/plugin/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  94. package/plugin/skills/writing-skills/render-graphs.js +169 -0
@@ -0,0 +1,209 @@
1
+ # Task Reviewer Prompt Template
2
+
3
+ Use this template when dispatching a task reviewer subagent. The reviewer
4
+ reads the task's diff once and returns two verdicts: spec compliance and
5
+ code quality.
6
+
7
+ **Purpose:** Verify one task's implementation matches its requirements (nothing
8
+ more, nothing less) and is well-built (clean, tested, maintainable)
9
+
10
+ ```
11
+ Subagent (general-purpose):
12
+ description: "Review Task N (spec + quality)"
13
+ model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
14
+ model silently inherits the session's most expensive one]
15
+ prompt: |
16
+ You are reviewing one task's implementation: first whether it matches its
17
+ requirements, then whether it is well-built. This is a task-scoped gate,
18
+ not a merge review — a broad whole-branch review happens separately after
19
+ all tasks are complete.
20
+
21
+ ## What Was Requested
22
+
23
+ Read the task brief: [BRIEF_FILE]
24
+
25
+ Global constraints from the spec/design that bind this task:
26
+ [GLOBAL_CONSTRAINTS]
27
+
28
+ ## What the Implementer Claims They Built
29
+
30
+ Read the implementer's report: [REPORT_FILE]
31
+
32
+ ## Diff Under Review
33
+
34
+ **Base:** [BASE_SHA]
35
+ **Head:** [HEAD_SHA]
36
+ **Diff file:** [DIFF_FILE]
37
+
38
+ Read the diff file once — it contains the commit list, a stat summary,
39
+ and the full diff with surrounding context, and it is your view of the
40
+ change. The diff's context lines ARE the changed files: do not Read a
41
+ changed file separately unless a hunk you must judge is cut off
42
+ mid-function — and say so in your report. Do not re-run git commands.
43
+ If the diff file is missing, fetch the diff yourself:
44
+ `git diff --stat [BASE_SHA]..[HEAD_SHA]` and `git diff [BASE_SHA]..[HEAD_SHA]`.
45
+ Do not crawl the broader codebase. Inspect code outside the diff only
46
+ to evaluate a concrete risk you can name — one focused check per named
47
+ risk, and name both the risk and what you checked in your report.
48
+ Cross-cutting changes are legitimate named risks: if the diff changes
49
+ lock ordering, a function or API contract, or shared mutable state,
50
+ checking the call sites is the right method.
51
+
52
+ Your review is read-only on this checkout. Do not mutate the working
53
+ tree, the index, HEAD, or branch state in any way.
54
+
55
+ ## You Do Not Dispatch Subagents
56
+
57
+ Do all of this review yourself. Never spawn a subagent to review part
58
+ of the diff, and never spawn another reviewer for a second opinion.
59
+ This process already provides every review seat the work gets; a
60
+ reviewer you spawn duplicates one of them at full cost, and its
61
+ verdict counts for nothing. If the diff feels too large for one
62
+ pass, review it in passes yourself and say so in your report.
63
+
64
+ ## Do Not Trust the Report
65
+
66
+ Treat the implementer's report as unverified claims about the code. It
67
+ may be incomplete, inaccurate, or optimistic. Verify the claims against
68
+ the diff. Design rationales in the report are claims too: "left it per
69
+ YAGNI," "kept it simple deliberately," or any other justification is the
70
+ implementer grading their own work. Judge the code on its merits — a
71
+ stated rationale never downgrades a finding's severity.
72
+
73
+ ## Tests
74
+
75
+ The implementer already ran the tests and reported results with TDD
76
+ evidence for exactly this code. Do not re-run the suite to confirm their
77
+ report. Run a test only when reading the code raises a specific doubt
78
+ that no existing run answers — and then a focused test, never a
79
+ package-wide suite, race detector run, or repeated/high-count loop. If
80
+ heavy validation seems warranted, recommend it in your report instead of
81
+ running it. If you cannot run commands in this environment, name the
82
+ test you would run.
83
+
84
+ Warnings or other noise in the implementer's reported test output are
85
+ findings — test output should be pristine.
86
+
87
+ Evidence you cannot see is not evidence that doesn't exist. If the
88
+ report or its test evidence looks truncated, or you cannot locate the
89
+ results it claims, re-read the file at its stated path — and if it is
90
+ genuinely missing or garbled, report that as a gap for the controller.
91
+ Re-running the suite to regenerate what you failed to read is not
92
+ verification; illegibility of the evidence is not invalidation of it.
93
+
94
+ ## Part 1: Spec Compliance
95
+
96
+ Compare the diff against What Was Requested:
97
+
98
+ - **Missing:** requirements they skipped, missed, or claimed without
99
+ implementing
100
+ - **Extra:** features that weren't requested, over-engineering, unneeded
101
+ "nice to haves"
102
+ - **Misunderstood:** right feature built the wrong way, wrong problem
103
+ solved
104
+
105
+ If the brief lists several files each with its own change (a batched
106
+ dispatch), check the diff against that list file by file: every listed
107
+ file must have its corresponding hunk. A listed file the diff never
108
+ touches is a Missing finding, no matter how clean the rest of the
109
+ batch looks.
110
+
111
+ If a requirement cannot be verified from this diff alone (it lives in
112
+ unchanged code or spans tasks), report it as a ⚠️ item instead of
113
+ broadening your search.
114
+
115
+ ## Part 2: Code Quality
116
+
117
+ **Code quality:**
118
+ - Clean separation of concerns?
119
+ - Proper error handling?
120
+ - DRY without premature abstraction?
121
+ - Edge cases handled?
122
+
123
+ **Tests:**
124
+ - Do the new and changed tests verify real behavior, not mocks?
125
+ - Are the task's edge cases covered?
126
+
127
+ **Structure:**
128
+ - Does each file have one clear responsibility with a well-defined interface?
129
+ - Are units decomposed so they can be understood and tested independently?
130
+ - Is the implementation following the file structure from the plan?
131
+ - Did this change create new files that are already large, or
132
+ significantly grow existing files? (Don't flag pre-existing file
133
+ sizes — focus on what this change contributed.)
134
+
135
+ Your report should point at evidence: file:line references for every
136
+ finding and for any check you would otherwise answer with a bare
137
+ "yes." A tight report that cites lines gives the controller everything
138
+ it needs.
139
+
140
+ Your final message is the report itself: begin directly with the
141
+ spec-compliance verdict. Every line is a verdict, a finding with
142
+ file:line, or a check you ran — no preamble, no process narration,
143
+ no closing summary.
144
+
145
+ ## Calibration
146
+
147
+ Categorize issues by actual severity. Not everything is Critical.
148
+ Important means this task cannot be trusted until it is fixed: incorrect
149
+ or fragile behavior, a missed requirement, or maintainability damage you
150
+ would block a merge over — verbatim duplication of a logic block,
151
+ swallowed errors, tests that assert nothing. "Coverage could be broader"
152
+ and polish suggestions are Minor.
153
+ If the plan or brief explicitly mandates something this rubric calls a
154
+ defect (a test that asserts nothing, verbatim duplication of a logic
155
+ block), that IS a finding — report it as Important, labeled
156
+ plan-mandated. The plan's authorship does not grade its own work; the
157
+ human decides.
158
+ Acknowledge what was done well before listing issues — accurate praise
159
+ helps the implementer trust the rest of the feedback.
160
+
161
+ ## Output Format
162
+
163
+ ### Spec Compliance
164
+
165
+ - ✅ Spec compliant | ❌ Issues found: [what's missing/extra/misunderstood,
166
+ with file:line references]
167
+ - ⚠️ Cannot verify from diff: [requirements you could not verify from the
168
+ diff alone, and what the controller should check — report alongside the
169
+ ✅/❌ verdict for everything you could verify]
170
+
171
+ ### Strengths
172
+ [What's well done? Be specific.]
173
+
174
+ ### Issues
175
+
176
+ #### Critical (Must Fix)
177
+ #### Important (Should Fix)
178
+ #### Minor (Nice to Have)
179
+
180
+ For each issue: file:line, what's wrong, why it matters, how to fix
181
+ (if not obvious).
182
+
183
+ ### Assessment
184
+
185
+ **Task quality:** [Approved | Needs fixes]
186
+
187
+ **Reasoning:** [1-2 sentence technical assessment]
188
+ ```
189
+
190
+ **Placeholders:**
191
+ - `[MODEL]` — REQUIRED: reviewer model per SKILL.md Model Selection
192
+ - `[BRIEF_FILE]` — REQUIRED: the task brief file (`bash scripts/task-brief PLAN N`,
193
+ run by its absolute path, from the working tree you're executing in,
194
+ prints the path; same file the implementer worked from)
195
+ - `[GLOBAL_CONSTRAINTS]` — the binding requirements copied verbatim from
196
+ the plan's Global Constraints section or the spec: exact values, formats,
197
+ and stated relationships between components (not process rules — those
198
+ are already in this template)
199
+ - `[REPORT_FILE]` — REQUIRED: the file the implementer wrote its detailed
200
+ report to
201
+ - `[BASE_SHA]` — commit before this task
202
+ - `[HEAD_SHA]` — current commit
203
+ - `[DIFF_FILE]` — REQUIRED: the path the controller wrote the review
204
+ package to (`bash scripts/review-package PLAN_FILE BASE HEAD`, run by its
205
+ absolute path, from the working tree you're executing in, prints the unique
206
+ path it wrote; the package never enters the controller's context)
207
+
208
+ **Reviewer returns:** Spec Compliance verdict (✅/❌/⚠️), Strengths, Issues
209
+ (Critical/Important/Minor), Task quality verdict
@@ -0,0 +1,283 @@
1
+ ---
2
+ name: systematic-debugging
3
+ description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
4
+ ---
5
+
6
+ # Systematic Debugging
7
+
8
+ ## Overview
9
+
10
+ **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
11
+
12
+ **Violating the letter of this process is violating the spirit of debugging.**
13
+
14
+ ## The Iron Law
15
+
16
+ ```
17
+ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
18
+ ```
19
+
20
+ If you haven't completed Phase 1, you cannot propose fixes.
21
+
22
+ ## When to Use
23
+
24
+ Use for ANY technical issue:
25
+ - Test failures
26
+ - Bugs in production
27
+ - Unexpected behavior
28
+ - Performance problems
29
+ - Build failures
30
+ - Integration issues
31
+
32
+ **Use this ESPECIALLY when:**
33
+ - Under time pressure (emergencies make guessing tempting)
34
+ - "Just one quick fix" seems obvious
35
+ - You've already tried multiple fixes
36
+ - Previous fix didn't work
37
+ - You don't fully understand the issue
38
+
39
+ **Don't skip when:**
40
+ - Issue seems simple (simple bugs have root causes too)
41
+ - You're in a hurry (rushing guarantees rework)
42
+ - Manager wants it fixed NOW (systematic is faster than thrashing)
43
+
44
+ ## The Four Phases
45
+
46
+ You MUST complete each phase before proceeding to the next.
47
+
48
+ ### Phase 1: Root Cause Investigation
49
+
50
+ **BEFORE attempting ANY fix:**
51
+
52
+ 1. **Read Error Messages Carefully**
53
+ - Don't skip past errors or warnings
54
+ - They often contain the exact solution
55
+ - Read stack traces completely
56
+ - Note line numbers, file paths, error codes
57
+
58
+ 2. **Reproduce Consistently**
59
+ - Can you trigger it reliably?
60
+ - What are the exact steps?
61
+ - Does it happen every time?
62
+ - If not reproducible → gather more data, don't guess
63
+
64
+ 3. **Check Recent Changes**
65
+ - What changed that could cause this?
66
+ - Git diff, recent commits
67
+ - New dependencies, config changes
68
+ - Environmental differences
69
+
70
+ 4. **Gather Evidence in Multi-Component Systems**
71
+
72
+ **WHEN system has multiple components (CI → build → signing, API → service → database):**
73
+
74
+ **BEFORE proposing fixes, add diagnostic instrumentation:**
75
+ ```
76
+ For EACH component boundary:
77
+ - Log what data enters component
78
+ - Log what data exits component
79
+ - Verify environment/config propagation
80
+ - Check state at each layer
81
+
82
+ Run once to gather evidence showing WHERE it breaks
83
+ THEN analyze evidence to identify failing component
84
+ THEN investigate that specific component
85
+ ```
86
+
87
+ **Example (multi-layer system):**
88
+ ```bash
89
+ # Layer 1: Workflow
90
+ echo "=== Secrets available in workflow: ==="
91
+ echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
92
+
93
+ # Layer 2: Build script
94
+ echo "=== Env vars in build script: ==="
95
+ printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
96
+
97
+ # Layer 3: Signing script
98
+ echo "=== Keychain state: ==="
99
+ security list-keychains
100
+ security find-identity -v
101
+
102
+ # Layer 4: Actual signing
103
+ codesign --sign "$IDENTITY" --verbose=4 "$APP"
104
+ ```
105
+
106
+ **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
107
+
108
+ 5. **Trace Data Flow**
109
+
110
+ **WHEN error is deep in call stack:**
111
+
112
+ See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
113
+
114
+ **Quick version:**
115
+ - Where does bad value originate?
116
+ - What called this with bad value?
117
+ - Keep tracing up until you find the source
118
+ - Fix at source, not at symptom
119
+
120
+ ### Phase 2: Pattern Analysis
121
+
122
+ **Find the pattern before fixing:**
123
+
124
+ 1. **Find Working Examples**
125
+ - Locate similar working code in same codebase
126
+ - What works that's similar to what's broken?
127
+
128
+ 2. **Compare Against References**
129
+ - If implementing pattern, read reference implementation COMPLETELY
130
+ - Don't skim - read every line
131
+ - Understand the pattern fully before applying
132
+
133
+ 3. **Identify Differences**
134
+ - What's different between working and broken?
135
+ - List every difference, however small
136
+ - Don't assume "that can't matter"
137
+
138
+ 4. **Understand Dependencies**
139
+ - What other components does this need?
140
+ - What settings, config, environment?
141
+ - What assumptions does it make?
142
+
143
+ ### Phase 3: Hypothesis and Testing
144
+
145
+ **Scientific method:**
146
+
147
+ 1. **Form Single Hypothesis**
148
+ - State clearly: "I think X is the root cause because Y"
149
+ - Write it down
150
+ - Be specific, not vague
151
+
152
+ 2. **Test Minimally**
153
+ - Make the SMALLEST possible change to test hypothesis
154
+ - One variable at a time
155
+ - Don't fix multiple things at once
156
+
157
+ 3. **Verify Before Continuing**
158
+ - Did it work? Yes → Phase 4
159
+ - Didn't work? Form NEW hypothesis
160
+ - DON'T add more fixes on top
161
+
162
+ 4. **When You Don't Know**
163
+ - Say "I don't understand X"
164
+ - Don't pretend to know
165
+ - Ask for help
166
+ - Research more
167
+
168
+ ### Phase 4: Implementation
169
+
170
+ **Fix the root cause, not the symptom:**
171
+
172
+ 1. **Create Failing Test Case**
173
+ - Simplest possible reproduction
174
+ - Automated test if possible
175
+ - One-off test script if no framework
176
+ - MUST have before fixing
177
+ - Use the `superpowers:test-driven-development` skill for writing proper failing tests
178
+
179
+ 2. **Implement Single Fix**
180
+ - Address the root cause identified
181
+ - ONE change at a time
182
+ - No "while I'm here" improvements
183
+ - No bundled refactoring
184
+
185
+ 3. **Verify Fix**
186
+ - Test passes now?
187
+ - No other tests broken?
188
+ - Issue actually resolved?
189
+ - Use the `superpowers:verification-before-completion` skill before claiming success
190
+
191
+ 4. **If Fix Doesn't Work**
192
+ - STOP
193
+ - Count: How many fixes have you tried?
194
+ - If < 3: Return to Phase 1, re-analyze with new information
195
+ - **If ≥ 3: STOP and question the architecture (step 5 below)**
196
+ - DON'T attempt Fix #4 without architectural discussion
197
+
198
+ 5. **If 3+ Fixes Failed: Question Architecture**
199
+
200
+ **Pattern indicating architectural problem:**
201
+ - Each fix reveals new shared state/coupling/problem in different place
202
+ - Fixes require "massive refactoring" to implement
203
+ - Each fix creates new symptoms elsewhere
204
+
205
+ **STOP and question fundamentals:**
206
+ - Is this pattern fundamentally sound?
207
+ - Are we "sticking with it through sheer inertia"?
208
+ - Should we refactor architecture vs. continue fixing symptoms?
209
+
210
+ **Discuss with your human partner before attempting more fixes**
211
+
212
+ This is NOT a failed hypothesis - this is a wrong architecture.
213
+
214
+ ## Red Flags - STOP and Follow Process
215
+
216
+ If you catch yourself thinking:
217
+ - "Quick fix for now, investigate later"
218
+ - "Just try changing X and see if it works"
219
+ - "Add multiple changes, run tests"
220
+ - "Skip the test, I'll manually verify"
221
+ - "It's probably X, let me fix that"
222
+ - "I don't fully understand but this might work"
223
+ - "Pattern says X but I'll adapt it differently"
224
+ - "Here are the main problems: [lists fixes without investigation]"
225
+ - Proposing solutions before tracing data flow
226
+ - **"One more fix attempt" (when already tried 2+)**
227
+ - **Each fix reveals new problem in different place**
228
+
229
+ **ALL of these mean: STOP. Return to Phase 1.**
230
+
231
+ **If 3+ fixes failed:** Question the architecture (see Phase 4.5)
232
+
233
+ ## your human partner's Signals You're Doing It Wrong
234
+
235
+ **Watch for these redirections:**
236
+ - "Is that not happening?" - You assumed without verifying
237
+ - "Will it show us...?" - You should have added evidence gathering
238
+ - "Stop guessing" - You're proposing fixes without understanding
239
+ - "Ultra-think this" - Question fundamentals, not just symptoms
240
+ - "We're stuck?" (frustrated) - Your approach isn't working
241
+
242
+ **When you see these:** STOP. Return to Phase 1.
243
+
244
+ ## Common Rationalizations
245
+
246
+ | Excuse | Reality |
247
+ |--------|---------|
248
+ | "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
249
+ | "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
250
+ | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
251
+ | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
252
+ | "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
253
+ | "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
254
+ | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
255
+ | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
256
+
257
+ ## Quick Reference
258
+
259
+ | Phase | Key Activities | Success Criteria |
260
+ |-------|---------------|------------------|
261
+ | **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
262
+ | **2. Pattern** | Find working examples, compare | Identify differences |
263
+ | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
264
+ | **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
265
+
266
+ ## When Process Reveals "No Root Cause"
267
+
268
+ If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
269
+
270
+ 1. You've completed the process
271
+ 2. Document what you investigated
272
+ 3. Implement appropriate handling (retry, timeout, error message)
273
+ 4. Add monitoring/logging for future investigation
274
+
275
+ **But:** 95% of "no root cause" cases are incomplete investigation.
276
+
277
+ ## Supporting Techniques
278
+
279
+ These techniques are part of systematic debugging and available in this directory:
280
+
281
+ - **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
282
+ - **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
283
+ - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
@@ -0,0 +1,158 @@
1
+ // Complete implementation of condition-based waiting utilities
2
+ // From: Lace test infrastructure improvements (2025-10-03)
3
+ // Context: Fixed 15 flaky tests by replacing arbitrary timeouts
4
+
5
+ import type { ThreadManager } from '~/threads/thread-manager';
6
+ import type { LaceEvent, LaceEventType } from '~/threads/types';
7
+
8
+ /**
9
+ * Wait for a specific event type to appear in thread
10
+ *
11
+ * @param threadManager - The thread manager to query
12
+ * @param threadId - Thread to check for events
13
+ * @param eventType - Type of event to wait for
14
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
15
+ * @returns Promise resolving to the first matching event
16
+ *
17
+ * Example:
18
+ * await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
19
+ */
20
+ export function waitForEvent(
21
+ threadManager: ThreadManager,
22
+ threadId: string,
23
+ eventType: LaceEventType,
24
+ timeoutMs = 5000
25
+ ): Promise<LaceEvent> {
26
+ return new Promise((resolve, reject) => {
27
+ const startTime = Date.now();
28
+
29
+ const check = () => {
30
+ const events = threadManager.getEvents(threadId);
31
+ const event = events.find((e) => e.type === eventType);
32
+
33
+ if (event) {
34
+ resolve(event);
35
+ } else if (Date.now() - startTime > timeoutMs) {
36
+ reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
37
+ } else {
38
+ setTimeout(check, 10); // Poll every 10ms for efficiency
39
+ }
40
+ };
41
+
42
+ check();
43
+ });
44
+ }
45
+
46
+ /**
47
+ * Wait for a specific number of events of a given type
48
+ *
49
+ * @param threadManager - The thread manager to query
50
+ * @param threadId - Thread to check for events
51
+ * @param eventType - Type of event to wait for
52
+ * @param count - Number of events to wait for
53
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
54
+ * @returns Promise resolving to all matching events once count is reached
55
+ *
56
+ * Example:
57
+ * // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
58
+ * await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
59
+ */
60
+ export function waitForEventCount(
61
+ threadManager: ThreadManager,
62
+ threadId: string,
63
+ eventType: LaceEventType,
64
+ count: number,
65
+ timeoutMs = 5000
66
+ ): Promise<LaceEvent[]> {
67
+ return new Promise((resolve, reject) => {
68
+ const startTime = Date.now();
69
+
70
+ const check = () => {
71
+ const events = threadManager.getEvents(threadId);
72
+ const matchingEvents = events.filter((e) => e.type === eventType);
73
+
74
+ if (matchingEvents.length >= count) {
75
+ resolve(matchingEvents);
76
+ } else if (Date.now() - startTime > timeoutMs) {
77
+ reject(
78
+ new Error(
79
+ `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`
80
+ )
81
+ );
82
+ } else {
83
+ setTimeout(check, 10);
84
+ }
85
+ };
86
+
87
+ check();
88
+ });
89
+ }
90
+
91
+ /**
92
+ * Wait for an event matching a custom predicate
93
+ * Useful when you need to check event data, not just type
94
+ *
95
+ * @param threadManager - The thread manager to query
96
+ * @param threadId - Thread to check for events
97
+ * @param predicate - Function that returns true when event matches
98
+ * @param description - Human-readable description for error messages
99
+ * @param timeoutMs - Maximum time to wait (default 5000ms)
100
+ * @returns Promise resolving to the first matching event
101
+ *
102
+ * Example:
103
+ * // Wait for TOOL_RESULT with specific ID
104
+ * await waitForEventMatch(
105
+ * threadManager,
106
+ * agentThreadId,
107
+ * (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
108
+ * 'TOOL_RESULT with id=call_123'
109
+ * );
110
+ */
111
+ export function waitForEventMatch(
112
+ threadManager: ThreadManager,
113
+ threadId: string,
114
+ predicate: (event: LaceEvent) => boolean,
115
+ description: string,
116
+ timeoutMs = 5000
117
+ ): Promise<LaceEvent> {
118
+ return new Promise((resolve, reject) => {
119
+ const startTime = Date.now();
120
+
121
+ const check = () => {
122
+ const events = threadManager.getEvents(threadId);
123
+ const event = events.find(predicate);
124
+
125
+ if (event) {
126
+ resolve(event);
127
+ } else if (Date.now() - startTime > timeoutMs) {
128
+ reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
129
+ } else {
130
+ setTimeout(check, 10);
131
+ }
132
+ };
133
+
134
+ check();
135
+ });
136
+ }
137
+
138
+ // Usage example from actual debugging session:
139
+ //
140
+ // BEFORE (flaky):
141
+ // ---------------
142
+ // const messagePromise = agent.sendMessage('Execute tools');
143
+ // await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
144
+ // agent.abort();
145
+ // await messagePromise;
146
+ // await new Promise(r => setTimeout(r, 50)); // Hope results arrive in 50ms
147
+ // expect(toolResults.length).toBe(2); // Fails randomly
148
+ //
149
+ // AFTER (reliable):
150
+ // ----------------
151
+ // const messagePromise = agent.sendMessage('Execute tools');
152
+ // await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
153
+ // agent.abort();
154
+ // await messagePromise;
155
+ // await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
156
+ // expect(toolResults.length).toBe(2); // Always succeeds
157
+ //
158
+ // Result: 60% pass rate → 100%, 40% faster execution