parallelizing

Files (2)

• SKILL.md
• agent-prompt-template.md · references/

SKILL.md (first lines)

# Parallelizing

Announce at start: "I'm applying the parallelizing skill to run these tasks concurrently."

## Decision Gate

Before dispatching, answer three questions:

1. **Are there 2+ distinct tasks?** If not, handle directly.
2. **Are they independent?** If tasks share state, edit the same files, or depend on each other's output, run them sequentially.
3. **Can each be scoped with full context?** If an agent would need your entire session history to operate, it is not a good candidate for dispatch.

All three must be yes. Otherwise, work sequentially.

## Scoping Agent Tasks

Each agent operates in isolation with zero inherited context. Construct everything it needs:

- **Boundary** — one file, one subsystem, one problem domain
- **Objective** — concrete deliverable ("make these 3 tests pass," "add validation to endpoints X and Y")
- **Constraints** — what NOT to touch ("do not modify production code," "only change files under src/auth/")
- **Deliverable format** — what to return ("summary of root cause and changes made")

See [references/agent-prompt-template.md](references/agent-prompt-template.md) for the standard prompt structure.

## Dispatch

```typescript
// All calls execute concurrently
Task("Fix agent-tool-abort.test.ts — 3 timing failures")
Task("Fix batch-completion.test.ts — event structure bug")
Task("Fix tool-approval-race.test.ts — missing async wait")
```

## Integration After Return

When agents complete:

1. **Read each summary** — understand what changed and why
2. **Check for conflicts** — did any agents touch overlapping files?
3. **Run the full test suite** — individual fixes can interact unexpectedly
4. **Spot-check agent work** — agents can make systematic errors (e.g., all using the same wrong pattern)

If conflicts exist, resolve manually before running tests.

## Prompt Anti-Patterns

| Problem | Bad | Better |
|---------|-----|--------|
| Scope too wide | "Fix all the tests" | "Fix the 3 failures in `auth.test.ts`" |
| Missing context | "Fix the race condition" | Paste error messages + test names |
| No guardrails | Agent refactors freely | "Only modify files under `src/auth/`" |
| Vague deliverable | "Fix it" | "Return: root cause, files changed, verification" |

## When NOT to Dispatch

- **Cascading failures** — fixing one may resolve others. Investigate the root first.
- **Exploratory work** — you do not yet know what is broken. Gather information before splitting.
- **Shared file edits** — two agents editing the same file produces merge conflicts or silent overwrites.
- **Context-heavy tasks** — if the agent needs to understand the full system architecture, sequential investigation is cheaper than reconstructing context.

## Gotchas

- **Agents editing the same file** — Even "independent" tasks can converge on a shared utility or config file. Audit file boundaries before dispatch.
- **Silent failures** — An agent may report success while introducing a subtle regression. The full-suite run in integration is not optional.
- **Over-parallelizing** — Dispatching 10 agents for 10 trivial tasks adds coordination overhead that exceeds the time saved. Reserve parallelization for tasks with real duration.
- **Stale context in prompts** — Copying outdated error messages or file paths into agent prompts causes agents to chase ghosts. Verify context freshness before dispatch.

## Integration

**Called by:**
- **orchestrating** — dispatches agents for independent plan steps
- **debugging** — parallel investigation of unrelated failures

**Pairs with:**
- **isolating** — each agent may need its own worktree for file-level isolation

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn