golid / rules

---
description: Use parallel subagents when auditing or editing 5+ independent files, the user asks to run in parallel, or plan-execution-loop dispatches parallel implement subagents
alwaysApply: false
---

# Parallel Subagents for Multi-File Operations

> **Thesis:** Sequential edits across many files waste time and lose context. Split independent work across subagents, verify after completion.

## When to invoke

- **5+ independent files** — auditing or editing across many files with no ordering dependencies between them
- **User request** — the user explicitly asks to run work in parallel or use subagents
- **Plan parallel slices** — `plan-execution-loop` dispatches parallel implement subagents for a multi-file slice

When a task involves **auditing or editing 5+ independent files**, prefer parallel subagents over sequential tool calls. If changes have ordering dependencies, keep dependent steps sequential.

## When to parallelize

- **Audits**: searching for patterns, checking consistency, or reviewing code across 5+ files
- **Edits**: renaming, fixing stale references, or applying the same pattern across 5+ files
- **Mixed**: audit first (parallel), then edit (parallel) based on findings

## How to split work

Group files by **independence** — changes that don't depend on each other go in separate subagents. Max 4 concurrent subagents.

Good splits:

- By layer: Docker/infra files | source code | documentation | config
- By concern: backend changes | frontend changes

Bad splits:

- Putting a TSX file and its CSS file in different subagents (coordinated rename)
- Splitting a function definition from its callers

## Pre-flight: predict shared-file collisions

Before dispatching, `rg` the plans/specs for file paths each subagent will touch. Flag any file appearing in 2+ subagents — typically `openapi.yaml`, module `spec.md` files, shared type files (`frontend/src/lib/api.ts`, `frontend/src/lib/constants.ts`), barrels, `internal/wire/routes.go`. These cause cherry-pick conflicts.

For each shared file, decide upfront: which subagent owns which section? Tell each subagent explicitly to make **additive** edits (new sections, new contiguous blocks) and **not restructure** unrelated content. Textual diffs that touch different lines in the same file merge cleanly; restructured files do not.

## Subagent instructions

Each subagent prompt must include:

1. The exact files to read/edit
2. The specific changes to make (before/after values, line numbers if known)
3. "Read each file before editing to verify exact content"

Use the fast model for mechanical renames; default model for changes requiring judgment.

## When subagents will commit code

If subagents will branch, commit, or otherwise touch git state:

- **Worktree isolation is mandatory.** Each subagent gets its own `git worktree`. NEVER let a subagent operate directly in the parent repo (e.g., `/workspace`).
- **Forbid destructive git ops on the parent repo.** Explicitly tell every subagent: do NOT run `git reset --hard`, `git clean -fd`, `git stash drop`, or `git checkout --force` outside their assigned worktree. A previous incident lost uncommitted user edits this way.
- **Forbid `git add -A`** — subagents must explicitly add only the files they changed, so untracked user state in the parent isn't accidentally swept in.
- **Isolate cross-cutting touches in a final commit.** When two subagents both edit shared files (openapi, specs, barrels), instruct each to put those edits in one dedicated final commit. Conflicts then land in one focused commit instead of mixed in with functional changes — much faster to resolve. This is the one legitimate exception to the "one logical change per commit" rule in `git-commits` — see "Parallel Shared-File Exception" there for what qualifies and what doesn't. Name it `chore: sweep-up shared-file edits from <batch-name>` and list the per-feature mapping in the body.
- **Cherry-pick order matters when collisions are expected.** Land the smaller / more additive branch first; the larger restructure second. The restructuring commit then carries the burden of merging the smaller changes into its new layout.
- **Cherry-pick ONE commit at a time when bringing back a worktree branch.** Bulk `git cherry-pick A B C D ...` will sometimes fail at commit 3+ with a phantom `Your local changes to the following files would be overwritten by merge` error against files that are demonstrably clean (`git status` shows nothing, `git diff HEAD` is empty). The bulk run aborts and silently rolls back commits that already landed, leaving a partial state that builds with mysterious missing-method errors. A simple loop (`for sha in A B C D ...; do git cherry-pick $sha; done`) avoids this entirely.

## After subagents complete

1. Run verification searches (`rg`) to confirm all changes applied and no regressions introduced.
2. If cherry-picking: build, vet, lint, and run the full test suite (not just touched packages) — cross-cutting refactors silently break unrelated callers.
3. Clean up worktrees and feature branches (`git worktree remove`, `git branch -D`) once changes are landed. Stale worktrees confuse future subagent dispatches.

If a subagent failed due to content mismatch, read the file and fix manually.