2649 Delegation 27a3024a

# Delegating Review to Sub-Agents

Instructions for the **parent agent** spawning review sub-agents. This file is NOT for the forked review agent itself.

## When Delegating This Skill

When using the Task tool to delegate this skill to a sub-agent, be explicit that:
1. The agent must invoke the Skill tool FIRST
2. This is a TEMPLATE + CODEBASE COMPLIANCE review (not a content quality review)
3. Each agent reviews ONE file only

---

## Sub-Agent Batching Rules

**Never have more than 4 concurrent review agents. Context window blowout is the #1 failure mode.**

When reviewing multiple phases, you MUST follow this pattern:

```
# CORRECT: Spawn 4, wait for ALL 4 to complete, then spawn next 4
Batch 1: Spawn agents for phases 01, 02, 03, 04 (run_in_background: true)
         → Wait: TaskOutput block: true for ALL 4
         → Read results, summarize
Batch 2: Spawn agents for phases 05, 06, 07, 08 (run_in_background: true)
         → Wait: TaskOutput block: true for ALL 4
         → Read results, summarize
```

```
# WRONG: Spawning all at once blows context window
Spawn agents for phases 01-12 simultaneously
→ 12 agents return ~5KB each = 60KB+ of results flooding context
→ Agent loses track, produces garbage summaries
→ Earlier results get compressed/lost
```

**Rules:**
1. **Maximum 4 agents at a time** — no exceptions
2. **`run_in_background: true`** on every Task tool call
3. **`TaskOutput` with `block: true`** to wait for completion — do NOT read streaming output
4. **Wait for ALL agents in a batch** to complete before spawning the next batch
5. **Summarize each batch** before moving to the next (prevents context bloat)

---

## Prompt Templates for Sub-Agents

**For plan.md review:**

```
Your FIRST action must be to call the Skill tool with:
- skill: "review-plan"
- args: "plans/[plan-folder]"

Do NOT do any other work until you have invoked that skill.

The skill will instruct you to:
1. Read the PLAN-TEMPLATE.md reference
2. Compare every section in plan.md against the template
3. Write a review file with pass/fail for each required section

This is a template compliance review — missing sections cause implementation failures downstream. Check every section exists.

After the skill completes, report the verdict and missing section count.
```

**For single phase review:**

```
Your FIRST action must be to call the Skill tool with:
- skill: "review-plan"
- args: "plans/[plan-folder] phase 01"

Do NOT do any other work until you have invoked that skill.

The skill will instruct you to:
1. Read the PHASE-TEMPLATE.md reference
2. Compare every section in phase-01-*.md against the template
3. Verify code blocks against actual codebase patterns
4. Auto-fix Critical/High/Medium issues directly in the phase file
5. Write a review file with pass/fail for EACH required section AND codebase issues

This is a TEMPLATE + CODEBASE COMPLIANCE review with auto-fix (Critical/High/Medium).
Check every section exists AND verify code blocks match real codebase patterns.

After the skill completes, report the verdict, section count, codebase issue count,
auto-fixed items, and any Low improvement suggestions for the main agent.
```

**Anti-patterns:**

```
# WRONG - Vague, agent skips skill
Use the Skill tool to invoke the /review-plan skill...

# WRONG - No context, agent does superficial review
Your FIRST action must be to call the Skill tool with:
- skill: "review-plan"
- args: "plans/folder phase 01"
# Missing: what the review involves

# WRONG - Multiple phases causes superficial reviews
- args: "plans/folder phases 01-08"
- args: "plans/folder all"

# WRONG - Spawning all agents at once
for phase in 01..12: spawn review agent  ← context blowout
```

The key difference: Include BOTH the imperative command AND explanation of what the review entails. One file per agent.

---

## Auto-Fix Behavior

Auto-fix of Critical, High, and Medium codebase issues is built into the `/review-plan` skill (Step 9). When delegating reviews, you do NOT need to add separate fix instructions. The forked agent will:

1. Complete the full review (template + codebase compliance)
2. Auto-fix Critical, High, and Medium issues directly in the phase file
3. Return a summary including what was fixed, what was deferred, and Low improvement suggestions

The delegation prompts above already account for this — no additional "review AND fix" composite prompts needed.

## After a Review Completes — Main Agent Responsibilities

**When the forked review agent returns, the main agent MUST act on the results:**

1. **If there are deferred items** (Critical/High the agent couldn't fix):
   - Present them to the user with the agent's reasoning for deferring
   - Ask the user how to proceed (fix them, skip them, or discuss)
   - Apply fixes the user approves

2. **If there are Medium/Low improvement suggestions:**
   - Medium/Low findings are valid quality items, not optional suggestions
   - Fix all items that are grounded in actual codebase patterns (reference file cited)
   - Only skip items that are clearly hallucinated:
     * Reference non-existent files
     * Contradict actual codebase conventions
     * Flag patterns that the reference file itself uses
   - For Low items, also skip purely cosmetic changes (comment style, whitespace)
   - Present any deferred items to user with rationale

3. **If the verdict is PASS with no deferred items:**
   - Confirm the phase is ready and move on

**Do NOT just echo the review summary and stop.** The review's value comes from acting on its findings. The forked agent does the analysis; the main agent closes the loop by fixing what remains.