Subagents complete analysis but fail to write artifact files

[williamthorsen]

Problem

During orchestrated runs, subagents complete their analysis work (many tool calls, full codebase exploration) but fail to write their output artifact file. The orchestrator records these as phase failures because it cannot find the expected artifact.

This occurs in 50-75% of reviewer dispatches. In one run, 3 of 4 reviewers failed; in another, 4 of 10 subagent dispatches produced no output.

Root cause

Subagents exhaust their `max_turns` budget doing analysis and get cut off before reaching the artifact-write step, which is the last action in their workflow.

Contributing factors:

1. `max_turns` is too low for typical analysis workload (aspect reviewers at 15 turns are especially tight)
2. The write step has no safety net — it's the last action in a linear pipeline, so it's always the first thing dropped when turns run out
3. No budget awareness — agents have no visibility into their turn count and cannot self-regulate
4. No efficiency guidance — agents dutifully read every changed file in full, even when the diff shows nothing relevant to their scope

Evidence

Agent	Tool uses	max_turns	Outcome
`aspect-silent-failure-reviewer`	13	15	Succeeded
`aspect-code-reviewer`	25-33	15	Failed
`aspect-test-reviewer`	22-29	15	Failed
`orchestrated-reviewer`	42	30	Failed

The one agent that consistently succeeds (`aspect-silent-failure-reviewer`) has the narrowest scope and uses the fewest turns.

Impact

• False `needs_manual_review` outcomes when all successful reviewers converge at `none`/`low`
• Lost analysis work — findings from failed agents are not captured
• Wasted compute — full turn budget consumed with no output

Proposed solution

Four independent safeguards (defense-in-depth):

1. Turn-budget awareness (all 10 subagents): Add `## Turn budget` section stating exact turn count and a HARD-GATE to reserve last 3 turns for artifact writing
2. Write-early pattern (4 reviewer agents): Restructure Process sections to write the artifact after initial analysis, before deep refinement — ensures partial output survives turn exhaustion
3. Efficiency guidance (3 reviewer agents): Diff-first approach, batch reads, skip irrelevant files
4. Moderate `max_turns` increase (3 aspect reviewers): 15 → 20 in frontmatter, SKILL.md table, and review-cycle dispatch

Acceptance criteria

• All 10 subagent definitions include a `## Turn budget` section with correct turn count
• All 4 reviewer agents use the write-early process pattern
• 3 reviewer agents (code, test, core) have efficiency guidance
• Aspect reviewer `maxTurns` updated to 20 in frontmatter, SKILL.md table, and review-cycle.md dispatch
• Turn counts in `## Turn budget` sections match `maxTurns` frontmatter values
• Turn budget table in SKILL.md matches all subagent frontmatter values

Files changed

File	Changes
`content/subagents/aspect-code-reviewer.md`	All 4 safeguards
`content/subagents/aspect-test-reviewer.md`	All 4 safeguards
`content/subagents/aspect-silent-failure-reviewer.md`	Safeguards 1, 2, 4
`content/subagents/orchestrated-reviewer.md`	Safeguards 1, 2, 3
`content/subagents/orchestrated-architect.md`	Safeguard 1
`content/subagents/orchestrated-planner.md`	Safeguard 1
`content/subagents/orchestrated-coder.md`	Safeguard 1
`content/subagents/plan-reviewer.md`	Safeguard 1
`content/subagents/plan-reviser.md`	Safeguard 1
`content/subagents/planner.md`	Safeguard 1
`content/skills/orchestrate/SKILL.md`	Safeguard 4 (table update)
`content/skills/orchestrate/modules/review-cycle.md`	Safeguard 4 (dispatch update)

Related

• Replace LLM-driven run-index.json assembly with MCP orchestration tools and structured return contracts #83 — Structured return contracts (closed)
• Update orchestrator skills to use MCP tools and v3 events #87 — Update orchestrator skills to use MCP tools (open)
• Create find-orchestration-savings skill to identify token waste in orchestrated runs #217 — Create /find-savings skill (reports on this bug's impact)

[williamthorsen]

New occurrence: run 20260305-184232Z (ticket #181)

Summary

Two different aspect reviewer agents failed to write artifact files in the same run, across two separate review rounds. This caused a false needs_manual_review outcome despite all actual findings being addressed and verified.

Details

Round 1 — aspect-code-reviewer failed:

• Dispatched with max_turns: 15, model: sonnet
• Agent returned an agentId and usage stats (62,816 tokens, 25 tool_uses, 90s)
• Expected artifact: 08_code-reviewer_code-review.md
• Artifact was never written to disk
• Other 3 reviewers (core, silent-failure, test) all wrote their artifacts successfully

Round 2 (re-review) — aspect-test-reviewer failed:

• Dispatched with max_turns: 15, model: sonnet
• Agent returned an agentId and usage stats (32,189 tokens, 22 tool_uses, 77s)
• Expected artifact: 12_test-reviewer_test-review.md
• Artifact was never written to disk
• Other 2 re-reviewers (core, silent-failure) both wrote their artifacts successfully

Impact

The orchestrator's fallback rule treats failed reviewers at their original severity:

• Code-reviewer failure → medium (default for failed agents)
• Test-reviewer failure → medium (original round 1 severity preserved)

This inflated the aggregated criticality to medium, which combined with the exhausted review budget (2/2 rounds), triggered needs_manual_review. In reality:

• All 8 original findings from round 1 were addressed by the coder
• The core reviewer verified all fixes as correct in round 2
• The silent-failure reviewer confirmed no remaining issues

The needs_manual_review status is entirely an artifact of the infrastructure failure, not code quality.

Observations

• Both failing agents used the same model (sonnet) with max_turns: 15
• Both had significant tool usage (25 and 22 tool_uses respectively), suggesting they ran meaningful analysis but never reached the artifact-write step
• The pattern matches Subagents complete analysis but fail to write artifact files #105's hypothesis: agents exhaust max_turns before reaching the write step
• Different agent types failed in different rounds — this is not specific to one agent implementation

Strengthens the case for

• Moving artifact-write instructions earlier in subagent prompts
• A "write first, refine later" pattern to capture partial output
• Increasing max_turns for aspect reviewers (currently 15 — may be insufficient for re-review prompts that include previous-findings context)
• Considering a fallback rule adjustment: when all successful re-reviewers converge at none/low, a failed reviewer's phantom severity shouldn't block convergence

[williamthorsen]

Additional occurrence from the same session (run 20260305-184232Z, ticket #181):

A manually dispatched orchestrated-reviewer (holistic review) also failed to write its artifact. Stats: 53,368 tokens, 51 tool_uses, 109s. Expected artifact: 13_reviewer_holistic-review.md. Never written.

That's 3 distinct agents failing to write artifacts in one session: aspect-code-reviewer (R1), aspect-test-reviewer (R2), and orchestrated-reviewer (holistic). The holistic reviewer had max_turns: 30 — so the max_turns: 15 hypothesis from the aspect reviewers doesn't fully explain the problem. Something else may be contributing.

[williamthorsen]

Additional data point from #213 run (20260307-140746Z)

During the Phase 4 parallel review dispatch, 3 of 4 reviewers failed to write their artifact files:

Agent	max_turns	Tool uses	Duration	Artifact written?
orchestrated-reviewer	30	42	160s	No
aspect-silent-failure-reviewer	15	13	58s	Yes
aspect-test-reviewer	15	29	77s	No
aspect-code-reviewer	15	33	69s	No

Observations

• The silent-failure reviewer succeeded with only 13 tool uses — well within its 15-turn budget. The other two aspect reviewers used 29 and 33 tool uses respectively, likely exhausting their 15-turn budgets on analysis before reaching the write step.
• The core reviewer had 30 max_turns and used 42 tool uses (160s) but still didn't write. This suggests the core reviewer may also be exhausting turns on exploration.
• This is consistent with the hypothesis from this issue: agents get caught in exploration loops and never transition to the output phase.

Possible mitigation

The successful agent (silent-failure reviewer) had the simplest review scope — focused specifically on error-handling patterns. The broader-scoped reviewers (core, test, code) had more files to analyze and more categories to assess, consuming turns before writing.

Consider:

• Increasing max_turns for aspect reviewers from 15 to 20-25
• Adding "write artifact first with preliminary findings, then refine" to prompts
• Tracking tool-use counts in reviewer_completed events for systematic analysis

[williamthorsen]

Implementation plan

Artifact-write safeguards implementation plan

Goal: Prevent subagents from exhausting their turn budgets before writing artifact files, using four independent safeguards.

Architecture: All changes are to markdown content files in packages/agents/content/. No TypeScript code changes. The safeguards are additive — they add new sections and restructure existing sections in subagent prompts, plus update the turn budget table in the orchestrate skill.

---

Task 1: Add turn-budget section to all 10 subagent definitions

Files:

• Modify: packages/agents/content/subagents/orchestrated-architect.md
• Modify: packages/agents/content/subagents/orchestrated-planner.md
• Modify: packages/agents/content/subagents/orchestrated-coder.md
• Modify: packages/agents/content/subagents/orchestrated-reviewer.md
• Modify: packages/agents/content/subagents/aspect-code-reviewer.md
• Modify: packages/agents/content/subagents/aspect-silent-failure-reviewer.md
• Modify: packages/agents/content/subagents/aspect-test-reviewer.md
• Modify: packages/agents/content/subagents/plan-reviewer.md
• Modify: packages/agents/content/subagents/plan-reviser.md
• Modify: packages/agents/content/subagents/planner.md

Add a ## Turn budget section immediately before ## Orchestrator return protocol (or before ## Constraints for planner.md). The turn count must match the maxTurns frontmatter value.

Section content:

## Turn budget

You have **{N} turns** (API round-trips) to complete your work. Each time you call tools and receive results counts as one turn.

<HARD-GATE>
**Reserve your last 3 turns for writing your artifact file and return block.** Writing your artifact is your primary deliverable — analysis that doesn't produce a written artifact is wasted work. If you are approaching your turn limit, stop analysis and write what you have.
</HARD-GATE>

Turn counts: architect=30, planner=40, coder=80, core-reviewer=30, aspect reviewers=20, plan-reviewer=30, plan-reviser=30, story-planner=40.

Commit: agents|feat: Add turn-budget awareness to all subagent prompts

---

Task 2: Restructure reviewer process sections with write-early pattern

Files: 4 reviewer agent definitions

Restructure each reviewer's ## Process section to place artifact writing after initial analysis, before deep refinement. Pattern:

1. Get the diff
2. Read changed files relevant to scope
3. Check relevance (aspect reviewers only — early exit if not applicable)
4. Form preliminary findings
5. Write artifact with current findings, criticality, and return block
6. Refine if turns remain — continue analysis and update the existing artifact

Key line for step 5: "A partial review is infinitely more valuable than no review."

Commit: agents|feat: Add write-early pattern to reviewer process sections

---

Task 3: Add efficiency guidance to reviewer agents

Files: aspect-code-reviewer.md, aspect-test-reviewer.md, orchestrated-reviewer.md

Add ### Efficiency subsection after Process, before Scope/Finding format:

• Diff-first: read the diff before reading full files
• Batch reads: use parallel tool calls
• Skip irrelevant files: skip files whose diffs show no issues in scope

The aspect-silent-failure-reviewer already has narrow scope and doesn't need this.

Commit: agents|feat: Add efficiency guidance to reviewer prompts

---

Task 4: Increase max_turns for aspect reviewers

Files:

• 3 aspect reviewer frontmatter: maxTurns: 15 → maxTurns: 20
• content/skills/orchestrate/SKILL.md: turn budget table rows 15 → 20
• content/skills/orchestrate/modules/review-cycle.md: 3 inline max_turns: 15 → max_turns: 20

Cross-check all SKILL.md table rows against subagent frontmatter values after the change.

Commit: agents|feat: Increase aspect reviewer turn budgets from 15 to 20