version: "1.0.0" name: delegating-work description: Use when a change is expected to span multiple files or modules, or when deciding whether to hand work to subagents, run them in parallel, or keep it in the main conversation.

Delegating work

Parallel readers, single writer. Research fans out. Design decisions and edits never do.

Gate

If the diff is describable in one sentence — a single-file fix, a rename, a log tweak — skip all of this and do the work. Test and review rules still apply. Running a pipeline over a one-line change is the most common way this skill gets misused.

The gate moves as the conversation grows, because the primary value of a subagent is isolation, not parallelism. Early in a session, a task under roughly five tool calls is cheaper inline. Once the conversation is large, the per-call tax on every subsequent turn is paid against the whole context, and a single subagent that contains verbose output — a test run, a log sweep, a grep-heavy exploration — earns its cost with no parallelism involved at all.

Two rules that get conflated

"Single writer" and "a fresh writer per task" are different claims, and confusing them produces bad decisions in both directions.

• Single writer is a concurrency constraint: never two agents editing at once. It is about

conflicting edits.

• A fresh subagent per task is a context strategy: deliberately discard context between units

of work.

Both satisfy single-writer. Choose between them on what dominates quality:

The third row decides more cases than the others. When a task's brief must specify what to keep, what to strip, and how it should read alongside its neighbours, you have already done the work — handing it off adds a translation loss and saves nothing. Never delegate understanding.

The second column's failure mode is real too: work that must cohere, split across cold starts, produces N variants that each defensively restate shared context. That is how one rule ends up duplicated across three files that then drift apart.

Phases

1. Scope. Pin the goal, what is affected, what is explicitly out of scope.

2. Research — fan out. Launch every applicable reader in one message, read-only, with an explicit model — vvkit:choosing-subagent-models. Readers are independent and never write. Three that usually apply: prior art in this repo; verification of any contract, schema or interface the change touches; the requirements source when a spec or ticket exists.

3. Plan — never delegated. Design decisions stay where the full conversation is. Splitting them across agents produces conflicting implicit assumptions. Agree the design first — vvkit:designing-changes — and write the plan down beside the design.

Several independent failures — different subsystems, no shared state, each understandable alone — are the case where research fan-out pays most: one read-only investigator per failure, each returning the root cause and the change it proposes. The fixes still land through one writer. When fixing one failure might fix the others, investigate them together first.

4. Implement — one writer. Exactly one writer at any moment. Executing a written plan, task by task, is vvkit:planning-changes. Choose fresh-per-task or full-context by the table above. Parallel implementers are never used: file disjointness is rarely enforceable, and shared project files make it worse.

5. Verify, then review. The build and test gate first. Then one independent reviewer that never saw your reasoning — reading the diff itself, not your account of it. Fresh context is a genuine advantage here, which is why review is the one stage that should always be delegated.

The spawn-prompt contract

Every spawn carries four things. Missing any one is the usual cause of a useless result.

1. Objective — the question, not the procedure. Over-prescribing steps yields shallow work.
2. What is already ruled out — so the agent doesn't re-derive dead ends.
3. Known paths — files, symbols, line numbers you already have.
4. An output contract — exact shape and a length cap. Without one, the result is unparseable

and floods the context you delegated to protect. Require a file:line or verbatim command output behind every claim, and verified facts listed apart from inferences. A claim with no location cannot be checked, and an inference mixed in with facts gets accepted as one.

A subagent receives no conversation history. Anything it needs must be in the prompt.

Accepting a result

A subagent's report is a claim about the work, not evidence of it. It describes what the agent intended, and it cites locations with the same fluency whether or not it read them.

• Read the cited `file:line` yourself for every claim a decision rests on. Skimming the report

is not checking it.

• Re-derive counts and outcomes from the machine. "Changed N places" is checked with

git diff --stat; "tests pass" by re-running them. A build, test or lint gate is judged by its output only.

• High-risk conclusions need a second opinion that never saw the first — data deletion,

security, production configuration, or anything the user will act on. Launch two independent agents on the same question, or one agent briefed to refute the first's answer, and accept only what both agents agree on or what the refuter failed to break. One agent's confident answer and its own re-check share every blind spot.

Common mistakes

Reference

Frontmatter fields, tool restrictions, memory options, isolation and anti-patterns: references/subagent-reference.md.