diff --git a/skills/dispatching-parallel-agents/SKILL.md b/skills/dispatching-parallel-agents/SKILL.md index 33b14859f..7c5188531 100644 --- a/skills/dispatching-parallel-agents/SKILL.md +++ b/skills/dispatching-parallel-agents/SKILL.md @@ -5,12 +5,36 @@ description: Use when facing 2+ independent tasks that can be worked on without # Dispatching Parallel Agents +## Table of Contents + +1. [Overview](#overview) +2. [Quick Reference Checklist](#quick-reference-checklist) +3. [When to Use](#when-to-use) +4. [The Pattern](#the-pattern) +5. [Agent Prompt Structure](#agent-prompt-structure) +6. [Common Mistakes](#common-mistakes) +7. [Verification](#verification) +8. [Key Benefits](#key-benefits) +9. [Reference Files](#reference-files) + ## Overview -When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel. +Multiple unrelated failures (different test files, different subsystems, different bugs) waste time when investigated sequentially. Each investigation is independent and can happen in parallel. **Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently. +## Quick Reference Checklist + +Use this checklist for rapid parallel dispatch: + +1. ☐ **Group failures by domain** - Identify independent subsystems +2. ☐ **Verify independence** - Confirm no shared state between problems +3. ☐ **Create focused prompts** - One clear scope per agent ([template](references/agent-prompt-template.md)) +4. ☐ **Dispatch in parallel** - Launch all agents simultaneously +5. ☐ **Review summaries** - Read what each agent found +6. ☐ **Check for conflicts** - Verify no overlapping changes +7. ☐ **Run full suite** - Validate all fixes work together + ## When to Use ```dot @@ -37,10 +61,11 @@ digraph when_to_use { - Each problem can be understood without context from others - No shared state between investigations -**Don't use when:** -- Failures are related (fix one might fix others) -- Need to understand full system state -- Agents would interfere with each other +**Avoid when:** +- Failures are related (fixing one might fix others) +- Full system state understanding required first +- Unknown failure cause - investigate before dispatching +- Agents would interfere (editing same files, using same resources) ## The Pattern @@ -59,7 +84,7 @@ Each agent gets: - **Specific scope:** One test file or subsystem - **Clear goal:** Make these tests pass - **Constraints:** Don't change other code -- **Expected output:** Summary of what you found and fixed +- **Expected output:** Summary of what found and fixed ### 3. Dispatch in Parallel @@ -86,74 +111,24 @@ Good agent prompts are: 2. **Self-contained** - All context needed to understand the problem 3. **Specific about output** - What should the agent return? -```markdown -Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts: - -1. "should abort tool with partial output capture" - expects 'interrupted at' in message -2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed -3. "should properly track pendingToolCount" - expects 3 results but gets 0 - -These are timing/race condition issues. Your task: - -1. Read the test file and understand what each test verifies -2. Identify root cause - timing issues or actual bugs? -3. Fix by: - - Replacing arbitrary timeouts with event-based waiting - - Fixing bugs in abort implementation if found - - Adjusting test expectations if testing changed behavior - -Do NOT just increase timeouts - find the real issue. - -Return: Summary of what you found and what you fixed. -``` +See the complete reusable template: **[Agent Prompt Template](references/agent-prompt-template.md)** ## Common Mistakes -**❌ Too broad:** "Fix all the tests" - agent gets lost -**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope - -**❌ No context:** "Fix the race condition" - agent doesn't know where -**✅ Context:** Paste the error messages and test names - -**❌ No constraints:** Agent might refactor everything -**✅ Constraints:** "Do NOT change production code" or "Fix tests only" - -**❌ Vague output:** "Fix it" - you don't know what changed -**✅ Specific:** "Return summary of root cause and changes" - -## When NOT to Use - -**Related failures:** Fixing one might fix others - investigate together first -**Need full context:** Understanding requires seeing entire system -**Exploratory debugging:** You don't know what's broken yet -**Shared state:** Agents would interfere (editing same files, using same resources) - -## Real Example from Session - -**Scenario:** 6 test failures across 3 files after major refactoring - -**Failures:** -- agent-tool-abort.test.ts: 3 failures (timing issues) -- batch-completion-behavior.test.ts: 2 failures (tools not executing) -- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0) - -**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions +| Anti-Pattern | Problem | Fix | +|-------------|---------|-----| +| "Fix all the tests" | Too broad, agent gets lost | Scope to one file/subsystem | +| "Fix the race condition" | No location context | Paste error messages and test names | +| No constraints | Agent might refactor everything | Add "Do NOT change production code" | +| "Fix it" | Vague output expectation | "Return summary of root cause and changes" | -**Dispatch:** -``` -Agent 1 → Fix agent-tool-abort.test.ts -Agent 2 → Fix batch-completion-behavior.test.ts -Agent 3 → Fix tool-approval-race-conditions.test.ts -``` - -**Results:** -- Agent 1: Replaced timeouts with event-based waiting -- Agent 2: Fixed event structure bug (threadId in wrong place) -- Agent 3: Added wait for async tool execution to complete - -**Integration:** All fixes independent, no conflicts, full suite green +## Verification -**Time saved:** 3 problems solved in parallel vs sequentially +After agents return: +1. **Review each summary** - Understand what changed +2. **Check for conflicts** - Did agents edit same code? +3. **Run full suite** - Verify all fixes work together +4. **Spot check** - Agents can make systematic errors ## Key Benefits @@ -162,19 +137,9 @@ Agent 3 → Fix tool-approval-race-conditions.test.ts 3. **Independence** - Agents don't interfere with each other 4. **Speed** - 3 problems solved in time of 1 -## Verification - -After agents return: -1. **Review each summary** - Understand what changed -2. **Check for conflicts** - Did agents edit same code? -3. **Run full suite** - Verify all fixes work together -4. **Spot check** - Agents can make systematic errors - -## Real-World Impact +## Reference Files -From debugging session (2025-10-03): -- 6 failures across 3 files -- 3 agents dispatched in parallel -- All investigations completed concurrently -- All fixes integrated successfully -- Zero conflicts between agent changes +| File | Description | +|------|-------------| +| [Agent Prompt Template](references/agent-prompt-template.md) | Reusable template with placeholder variables | +| [Example Session](references/example-session.md) | Real debugging session demonstrating the pattern | diff --git a/skills/dispatching-parallel-agents/references/agent-prompt-template.md b/skills/dispatching-parallel-agents/references/agent-prompt-template.md new file mode 100644 index 000000000..4dcba7856 --- /dev/null +++ b/skills/dispatching-parallel-agents/references/agent-prompt-template.md @@ -0,0 +1,79 @@ +# Agent Prompt Template + +Use this template when dispatching parallel agents for independent problem domains. + +## Template Structure + +```markdown +Fix the {{NUMBER}} failing tests in {{FILE_PATH}}: + +{{NUMBERED_LIST_OF_FAILURES}} + +These are {{PROBLEM_TYPE}} issues. Your task: + +1. Read the test file and understand what each test verifies +2. Identify root cause - {{DIAGNOSTIC_QUESTIONS}} +3. Fix by: + - {{FIX_APPROACH_1}} + - {{FIX_APPROACH_2}} + - {{FIX_APPROACH_3}} + +Do NOT {{CONSTRAINTS}}. + +Return: {{EXPECTED_OUTPUT_FORMAT}} +``` + +## Placeholder Definitions + +| Placeholder | Description | Example | +|------------|-------------|---------| +| `{{NUMBER}}` | Count of failures in scope | `3` | +| `{{FILE_PATH}}` | Relative path to test file | `src/agents/agent-tool-abort.test.ts` | +| `{{NUMBERED_LIST_OF_FAILURES}}` | Test names with error context | See below | +| `{{PROBLEM_TYPE}}` | Category of issue | `timing/race condition`, `null reference`, `async` | +| `{{DIAGNOSTIC_QUESTIONS}}` | What agent should investigate | `timing issues or actual bugs?` | +| `{{FIX_APPROACH_N}}` | Allowed fix strategies | `Replace arbitrary timeouts with event-based waiting` | +| `{{CONSTRAINTS}}` | What NOT to do | `just increase timeouts - find the real issue` | +| `{{EXPECTED_OUTPUT_FORMAT}}` | What agent returns | `Summary of what you found and what you fixed` | + +## Example: Filled Template + +```markdown +Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts: + +1. "should abort tool with partial output capture" - expects 'interrupted at' in message +2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed +3. "should properly track pendingToolCount" - expects 3 results but gets 0 + +These are timing/race condition issues. Your task: + +1. Read the test file and understand what each test verifies +2. Identify root cause - timing issues or actual bugs? +3. Fix by: + - Replacing arbitrary timeouts with event-based waiting + - Fixing bugs in abort implementation if found + - Adjusting test expectations if testing changed behavior + +Do NOT just increase timeouts - find the real issue. + +Return: Summary of what you found and what you fixed. +``` + +## Prompt Quality Checklist + +Before dispatching, verify the prompt is: + +- [ ] **Focused** - Single clear problem domain +- [ ] **Self-contained** - All context needed to understand the problem +- [ ] **Specific about output** - Clear expectation for what agent returns +- [ ] **Constrained** - Boundaries on what NOT to change +- [ ] **Actionable** - Concrete steps agent can follow + +## Common Anti-Patterns + +| Anti-Pattern | Problem | Fix | +|-------------|---------|-----| +| "Fix all the tests" | Too broad, agent gets lost | Scope to one file/subsystem | +| "Fix the race condition" | No context about location | Paste error messages and test names | +| No constraints | Agent might refactor everything | Add "Do NOT change production code" | +| "Fix it" | Vague output expectation | "Return summary of root cause and changes" | diff --git a/skills/dispatching-parallel-agents/references/example-session.md b/skills/dispatching-parallel-agents/references/example-session.md new file mode 100644 index 000000000..7a868716e --- /dev/null +++ b/skills/dispatching-parallel-agents/references/example-session.md @@ -0,0 +1,80 @@ +# Real-World Example: Parallel Agent Debugging Session + +This example demonstrates the parallel agent pattern applied to a real debugging session (2025-10-03). + +## Initial Situation + +**Context:** 6 test failures across 3 files after major refactoring + +**Failures identified:** +| File | Failures | Category | +|------|----------|----------| +| `agent-tool-abort.test.ts` | 3 | Timing issues | +| `batch-completion-behavior.test.ts` | 2 | Tools not executing | +| `tool-approval-race-conditions.test.ts` | 1 | Execution count = 0 | + +## Decision Analysis + +**Question:** Are these failures independent? + +**Analysis:** +- Abort logic is separate from batch completion +- Batch completion is separate from race condition handling +- No shared state between subsystems +- Each can be investigated without context from others + +**Decision:** ✅ Independent domains → Dispatch parallel agents + +## Agent Dispatch + +Three agents dispatched simultaneously: + +``` +Agent 1 → Fix agent-tool-abort.test.ts (3 failures) +Agent 2 → Fix batch-completion-behavior.test.ts (2 failures) +Agent 3 → Fix tool-approval-race-conditions.test.ts (1 failure) +``` + +## Agent Results + +### Agent 1: Abort Tests +**Root Cause:** Arbitrary timeouts causing flaky behavior +**Fix:** Replaced timeouts with event-based waiting +**Files Changed:** `agent-tool-abort.test.ts` + +### Agent 2: Batch Completion Tests +**Root Cause:** Event structure bug - `threadId` in wrong place +**Fix:** Corrected event payload structure +**Files Changed:** `batch-completion-behavior.test.ts`, `event-handler.ts` + +### Agent 3: Race Condition Tests +**Root Cause:** Test not waiting for async tool execution +**Fix:** Added wait for async tool execution to complete +**Files Changed:** `tool-approval-race-conditions.test.ts` + +## Integration + +**Conflict Check:** +- Agent 1 touched abort test file only ✅ +- Agent 2 touched batch test + event handler ✅ +- Agent 3 touched race condition test only ✅ +- No overlapping file changes ✅ + +**Full Suite Run:** All tests pass ✅ + +## Metrics + +| Metric | Value | +|--------|-------| +| Total failures | 6 | +| Agents dispatched | 3 | +| Files fixed | 4 | +| Conflicts | 0 | +| Time multiplier | ~3x faster than sequential | + +## Key Takeaways + +1. **Domain separation was correct** - Fixes were truly independent +2. **No agent conflicts** - Each worked in isolated scope +3. **Parallel execution saved time** - 3 problems solved in time of 1 +4. **Clear prompts produced clear results** - Each agent knew exactly what to investigate