deep-work

name	deep-work
description	Run a large, multi-place, uncertain task to completion via "plan → adversarial review → serial execute → synthesize & verify." Trigger: cross-file refactor, data migration, large feature build, system audit, deep research — tasks that can't be done in one pass and touch many places. Manual invocation: /deep-work.

deep-work — Multi-Agent Orchestration

Take a task too big to force through in a single pass and run it through four roles: Planner → Adversarial Reviewer → Executor pool → Synthesizer. Complex tasks usually fail not from a lack of intelligence, but from acting too fast, never challenging the plan, and not verifying when done.

Route first

This skill is the conductor. Before running the full loop, route:

• The task is a codebase audit / production-readiness review → use deep-analysis (it already runs readers → skeptics → roadmap with the right schemas).
• The task is a defined feature or bugfix → use implementation / /implement.
• The task is a broad, multi-place execution that is neither (large refactor, migration, multi-source research) → run the four stages below, delegating slices to implementer agents and challenges to adversarial-verify.
• If the shared board must outlive this context window (multi-session work) → persist it under thoughts/<task-slug>/ per the thoughts skill, and resume from it next session.

When to use / not use

Use: refactors across ≥3 files, data migrations, large features, system audits, research needing many sources — any task where getting one spot wrong sets off a chain reaction.

Don't use (overkill): single-file edits, answering a question, looking up one value, running one command. Do these directly.

Rule of thumb: if it takes several steps and you're not yet sure of the details of each step → use it.

---

The four stages

Stage 1 — Plan (Planner)

Don't act yet. Break the task into independent subtasks, each labeled with:

• What it changes (files/scope)
• What it depends on (which subtask must finish first)
• Safety level (touches a core many things depend on → mark "high risk")
• (only if you'll parallelize) Which files it shares with a sibling subtask — so two otherwise-independent slices that collide on one file can be put in different waves (Stage 3) instead of forced fully serial

Produce a subtask list. This stage only thinks; it doesn't do.

Stage 2 — Adversarial Review

Hand the Stage 1 plan to an independent agent to challenge — ideally from another angle. Prompt it:

This is a task plan. Your job is not to affirm it — find where it will fail.
Assume this plan has a 60% chance of missing something. Challenge specifically:
- Which subtasks have hidden dependencies, so the serial order is wrong?
- Which "assumed simple" subtasks actually ripple into other places?
- Is there a simpler approach (subtraction) that avoids doing this much?
- Which steps, once done, can't be verified for correctness?
Support every challenge with ls / grep / reading real files — not guesses.

Problems surfaced → revise the plan. This is the highest-value stage — don't skip it. The adversarial-verify skill runs exactly this move and can be called here directly.

Stage 3 — Serial Execution (Executors)

Execute subtask by subtask. Iron rule: subtasks that touch the same git working tree run serially, never in parallel — parallel agents eat each other's staged changes and commits end up mismatched. Only unrelated subtasks touching disjoint files run in parallel.

Give each executor a dead-spec, don't let it explore on its own:

• Which file, which lines, changed to what
• How to verify when done (which test / what smoke check)
• One subtask, one commit (atomic)

At scale, four optional refinements — defaults above stay; reach for these only when the parallel set is large enough that the default leaves real time on the table:

• Scout once, share once. Before fanning out >1 executor over a shared codebase, scout the shared facts yourself and bake them into one common preamble every executor gets (the way deep-analysis builds its CTX), so each spends its budget on its slice instead of re-deriving the architecture. Keep each slice's dead-spec; add the shared layer above it.
• Cap the fan-out. Honor any owner ceiling on concurrent mutating agents (e.g. a max_parallel_agents memory); absent one, start with a small fan-out and widen only once disjointness is proven. Read-only agents (e.g. deep-analysis readers) aren't capped.
• Waves, not blanket-serial. The iron rule sends same-tree work serial. When several independent slices collide only on one shared file, you may instead group them into waves — run the disjoint slices in parallel (wave 1), then the colliding slice alone (wave 2) — recovering the parallelism a blanket serial throws away. Truly-coupled work still runs serial; waves are only for independent slices that happen to share a file.
• Worktrees — the last resort. When slices genuinely can't be made disjoint and waves would serialize too much (many slices all mutating overlapping files), isolate each agent in its own checkout — git worktree add, or a Workflow with isolation: 'worktree' — and integrate the branches yourself. The merge conflicts are yours to resolve, so this earns its keep only when the parallelism saved outweighs the merge cost. The verify gates are per-worktree safe — each worktree carries its own ledger, so an agent in one can't satisfy or clobber another's gate (the gate suite's worktree-isolation test proves it). Disjoint-parallel and waves stay the defaults; reach for this only when both can't hold.

Stage 4 — Synthesize & Verify

After all subtasks are done:

• Converge the results; check the whole achieves the original task.
• Verify the root-cause fix took effect — run end-to-end tests, look at real output.
• Don't accept a self-reported "I'm done." Look at evidence (logs / green tests / actual behavior), not the agent's claim that it finished.

Verification finds it wasn't really fixed → go back to Stage 1 and re-plan that part.

---

Flow

Plan (think only)
   → Adversarial review (independent agent finds plan holes; must look at real files)
   → Serial execute (dead-spec / same git tree serial / atomic commits)
   → Synthesize & verify (real evidence, not self-reports)
   → if it doesn't pass, re-plan

Key disciplines

• Stage 1 thinks only — the most expensive failure is charging ahead on a wrong assumption.
• Don't skip Stage 2 — one independent challenge beats re-thinking it yourself.
• Stage 3 — serial to prevent races + dead-spec.
• Stage 4 — verify real evidence, don't trust self-reports.