# Investigation: Researcher Agent Turn Budget Exhaustion

**Date**: 2026-03-07
**Investigator**: Rex (nw-troubleshooter)
**Status**: Complete
**Severity**: High -- recurring knowledge loss, wasted tokens

---

## Problem Statement

The `/nw:research` command dispatches `nw-researcher` (Nova) which frequently exhausts its turn budget before producing any written output. The agent spends most turns on web searches and file reads, then returns nothing useful. Knowledge gathered during research is lost when the agent runs out of turns before writing.

---

## Evidence Summary

| Source | File | Key Finding |
|--------|------|-------------|
| Agent definition | `nWave/agents/nw-researcher.md:6` | `maxTurns: 30` |
| Software crafter | `nWave/agents/nw-software-crafter.md:6` | `maxTurns: 50` (67% more) |
| Solution architect | `nWave/agents/nw-solution-architect.md:6` | `maxTurns: 50` (67% more) |
| DES config | `src/des/config/des_defaults.yaml:14` | `research: 35` (DES default for research tasks) |
| DES orchestrator | `src/des/application/orchestrator.py:546-547` | Research commands bypass DES validation entirely -- returns empty string |
| TIMEOUT_INSTRUCTION | `src/des/domain/timeout_instruction_template.py:63-67` | Checkpoints are TDD-specific (PREPARE, RED, GREEN, REFACTOR) -- inapplicable to research |
| Researcher workflow | `nWave/agents/nw-researcher.md:51-69` | 4 phases, writing happens in Phase 4 (last phase) |
| Researcher skills | `nWave/skills/researcher/*.md` | 4 skill files loaded across 3 phases before writing |
| Research command | `nWave/tasks/nw/research.md:8` | Wave: CROSS_WAVE -- no DES enforcement |

---

## Toyota 5 Whys Analysis

### Branch A: No Progressive Output (Primary Root Cause)

```
WHY 1A: Researcher produces no written output before exhausting turns
  [Evidence: Agent workflow defines 4 sequential phases; writing occurs
   only in Phase 4 "Synthesize and Produce Output" (nw-researcher.md:67-69)]

  WHY 2A: Agent must complete Phases 1-3 before reaching Phase 4
    [Evidence: Phase gates are sequential -- Phase 2 requires "3+ sources
     from trusted domains" (nw-researcher.md:59); Phase 3 requires "all
     cited sources trusted; major claims have 3+ cross-references"
     (nw-researcher.md:64); Phase 4 says "Write document" (nw-researcher.md:69)]

    WHY 3A: Research methodology prescribes full gathering before any writing
      [Evidence: research-methodology.md defines output template as a single
       monolithic document (lines 12-61). No concept of incremental output.
       The distillation workflow (lines 63-80) also assumes "Read comprehensive
       research" as input -- implying Phase 1 produces the full document first.]

      WHY 4A: Research methodology was designed for human research workflow,
              not turn-constrained agent workflow
        [Evidence: No mention of "turns", "budget", "checkpoint", or
         "partial" anywhere in research-methodology.md. No mention of
         "progressive writing" or "incremental output". The template
         assumes unlimited time to complete. Compare with software-crafter
         which has explicit COMMIT phase after each GREEN (nw-software-crafter.md:186)
         and TIMEOUT_INSTRUCTION in execute.md:134-137.]

        WHY 5A: Agent design process did not account for the fundamental
                difference between turn-bounded work (research) and
                state-preserving work (TDD)
          [Evidence: TDD workflow has natural checkpoints -- each GREEN+COMMIT
           cycle produces durable artifacts (committed code). Research has no
           equivalent checkpoint pattern. The TIMEOUT_INSTRUCTION template
           (timeout_instruction_template.py:63-67) maps checkpoints to TDD
           phases only: "Turn ~10: PREPARE and RED", "Turn ~25: GREEN",
           "Turn ~40: REFACTOR", "Turn ~50: COMMIT". No research-phase
           equivalent exists.]
```

**ROOT CAUSE A**: Research methodology lacks progressive output checkpoints. Unlike TDD (which commits after each green cycle), research has no mechanism to persist intermediate findings. The entire methodology assumes a single write-at-the-end pattern.

---

### Branch B: No Turn Budget Awareness

```
WHY 1B: Researcher does not regulate its pace against available turns
  [Evidence: nw-researcher.md contains zero mentions of "turn",
   "budget", or "pace". No instruction tells the agent how many
   turns it has or when to transition from gathering to writing.]

  WHY 2B: Research command bypasses DES validation entirely
    [Evidence: orchestrator.py:546-547 returns empty string for research
     commands. The _get_validation_level method (orchestrator.py:419-436)
     returns "none" for /nw:research. VALIDATION_COMMANDS only includes
     /nw:execute and /nw:develop.]

    WHY 3B: DES was designed for TDD enforcement, not general turn management
      [Evidence: DES's TIMEOUT_INSTRUCTION (timeout_instruction_template.py)
       has TDD-specific milestones. DES's MANDATORY_SECTIONS validator
       (validator.py:56-63) checks for TDD-specific sections. The entire
       DES system assumes execute/develop workflow.]

      WHY 4B: CROSS_WAVE agents were treated as "outside DES scope"
        [Evidence: research.md:8 declares "Wave: CROSS_WAVE". The DES
         orchestrator explicitly classifies research as "none" validation
         level (orchestrator.py:428). No alternative turn management
         mechanism was created for cross-wave agents.]

        WHY 5B: Turn management was conflated with TDD enforcement rather
                than being a general agent concern
          [Evidence: DES config (des_defaults.yaml:14) defines
           "research: 35" as a turn limit, showing the CONCEPT of
           research turn limits exists in configuration. But this config
           is never surfaced to the researcher agent because the DES
           pipeline short-circuits for non-validation commands. The
           infrastructure exists but is not connected.]
```

**ROOT CAUSE B**: Turn budget awareness is embedded in the DES/TDD pipeline rather than being a general capability available to all agents. Research bypasses DES, so the researcher has no self-regulation mechanism.

---

### Branch C: Expensive Per-Turn Operations

```
WHY 1C: 30 turns is consumed rapidly during research
  [Evidence: maxTurns: 30 (nw-researcher.md:6). Research requires:
   loading 4 skill files across 3 phases (lines 43-48), web searches
   with WebSearch tool, web page fetches with WebFetch tool, local
   file reads with Read/Glob/Grep, source verification, and cross-
   referencing. A single source verification chain (search + fetch +
   validate) costs 3-5 turns minimum.]

  WHY 2C: The "3+ sources per major claim" requirement multiplies turn cost
    [Evidence: research-methodology.md:85-86 requires "Min 3 independent
     sources for major claims". source-verification.md:19-25 requires
     finding 2+ independent sources not citing each other, verifying
     independence, and comparing. For a topic with 5 major claims,
     that is 15+ source verifications = 45-75 turns for verification
     alone -- exceeding the 30-turn budget before writing starts.]

    WHY 3C: Quality standards were designed for thoroughness, not turn efficiency
      [Evidence: The research quality standards (research-methodology.md:83-97)
       define 5 quality gates, all requiring extensive verification. The
       source-verification skill (source-verification.md) adds bias detection
       checklist (7 items per source), circular reference detection, and
       reputation tier classification. These are excellent standards for
       research quality but were not balanced against turn constraints.]

      WHY 4C: No diminishing-returns detection or "good enough" threshold
        [Evidence: No mention of "diminishing returns", "saturation",
         "sufficient", or "enough" in any researcher skill file. The
         agent has no instruction to stop searching when redundant
         information is found. Compare: software-crafter has "If stuck
         after 3 attempts" escalation (nw-software-crafter.md:187). The
         researcher has no equivalent circuit breaker for research depth.]

        WHY 5C: Research quality was defined as an absolute standard rather
                than a budget-relative standard
          [Evidence: The "3+ sources per claim" is a hard requirement with
           no "within available turns" qualifier. In operational-safety.md:48-49,
           the circuit breaker pattern exists but only for tool failures
           ("After 3 consecutive failures"), not for turn budget depletion.
           No mechanism says "if turns < N, reduce source requirements to 2"
           or "write what you have so far".]
```

**ROOT CAUSE C**: Research quality standards are absolute (3+ sources per claim) with no adaptation to the available turn budget. The standards are excellent for quality but create an impossible contract when combined with a 30-turn limit.

---

### Branch D: Skill Loading Overhead

```
WHY 1D: A significant fraction of turns is consumed before research begins
  [Evidence: nw-researcher.md:43-48 prescribes loading skills at 3 separate
   phases: Phase 2 loads authoritative-sources.md + operational-safety.md;
   Phase 3 loads source-verification.md; Phase 4 loads research-methodology.md.
   That is 4 Read operations for skill files alone. Combined with the agent
   definition itself being loaded by the framework, this is 5+ turns of
   pure overhead before a single search is performed.]

  WHY 2D: Skills are loaded incrementally per-phase rather than upfront
    [Evidence: The skill loading table (nw-researcher.md:43-48) specifies
     different skills per phase. This is the standard nWave pattern --
     software-crafter also loads skills per-phase (nw-software-crafter.md:155-167).
     But software-crafter has 50 turns (nw-software-crafter.md:6) while
     researcher has 30, making the proportional overhead much higher
     (17% of budget for researcher vs 10% for crafter).]

    WHY 3D: Researcher has the same turn budget as agents with simpler workflows
      [Evidence: Researcher maxTurns=30 matches troubleshooter (30),
       acceptance-designer (30), and documentarist (30). But the researcher's
       workflow requires web searches (2-3 turns each), source fetches
       (1-2 turns each), and cross-referencing -- operations unavailable
       to other 30-turn agents. DES config (des_defaults.yaml:14) sets
       research type at 35 turns, but this is not applied to the agent.]

      WHY 4D: maxTurns was not calibrated against actual turn consumption per workflow
        [Evidence: The 30-turn budget appears to be a default standard tier
         (des_defaults.yaml:13 shows "standard: 30"). Agents requiring more
         turns (software-crafter, solution-architect, product-owner,
         product-discoverer, functional-software-crafter) all have 50.
         The researcher was categorized as "standard" despite having web-
         dependent operations that are more expensive than local file
         operations.]

        WHY 5D: Agent turn budgets were set by role category rather than
                by workflow analysis
          [Evidence: All "standard" agents got 30. All "complex" agents
           got 50. The DES config (des_defaults.yaml:10-15) defines
           categories (quick:15, background:25, standard:30, research:35,
           complex:50) but the researcher agent uses the "standard" tier
           (30) rather than the "research" tier (35) or "complex" tier (50)
           that its workflow demands.]
```

**ROOT CAUSE D**: The researcher's maxTurns (30) was set by role category ("standard") rather than calibrated to its actual workflow demands. Its web-dependent operations make each turn more expensive than local-only agents in the same tier, while the DES config's own "research: 35" tier is not applied.

---

## Cross-Validation

### Root Cause A + B + C + D: Consistent?

Yes. All four root causes are independent and mutually reinforcing:
- (A) No progressive output means ALL work is lost if turns run out
- (B) No turn awareness means the agent cannot self-regulate
- (C) Absolute quality standards mean the agent cannot adapt to budget
- (D) Insufficient turn budget means the agent hits the wall sooner

If any single root cause were addressed alone, the problem would be mitigated but not fully solved:
- Fix A only (progressive output): agent writes partials but still spends 80% on gathering
- Fix B only (turn awareness): agent knows budget is low but has no mechanism to act on it
- Fix C only (adaptive quality): agent reduces standards but still writes everything at end
- Fix D only (more turns): agent has more room but still risks the same pattern with complex topics

All four must be addressed for robust prevention.

### Do Root Causes Explain All Symptoms?

| Symptom | Explained By |
|---------|-------------|
| Agent produces no written output | ROOT CAUSE A (write-at-end pattern) |
| Agent spends most turns on web searches | ROOT CAUSE C (3+ sources per claim) + ROOT CAUSE D (insufficient budget) |
| Knowledge gathered is lost | ROOT CAUSE A (no checkpoints) + ROOT CAUSE B (no budget awareness) |
| Problem is recurring | ROOT CAUSE B (no self-regulation) -- agent cannot learn from past exhaustion |

All symptoms explained. No contradictions between root causes.

---

## Comparison with Well-Functioning Agents

### Software Crafter (maxTurns: 50, works well)

| Property | Software Crafter | Researcher |
|----------|-----------------|------------|
| Turn budget | 50 | 30 |
| Natural checkpoints | Yes -- each GREEN+COMMIT cycle | None |
| Progressive output | Yes -- code committed after each cycle | No -- single write at end |
| Budget awareness | Yes -- TIMEOUT_INSTRUCTION with turn milestones | None |
| Phase transitions | Enforced by DES (5 phases with gates) | Self-managed (4 phases, no enforcement) |
| "Stuck" protocol | After 3 attempts, escalate (line 187) | None |
| Quality adaptation | Test budget = 2x behaviors (bounded) | 3+ sources per claim (unbounded) |

### Solution Architect (maxTurns: 50, works well)

| Property | Solution Architect | Researcher |
|----------|-------------------|------------|
| Turn budget | 50 | 30 |
| Output type | Architecture document (single write) | Research document (single write) |
| Web dependency | None (local analysis) | Heavy (WebSearch + WebFetch) |
| Scope control | Quality-attribute-driven narrowing | "5-12 sources per topic" (broad) |
| Progressive output | Phases produce intermediate artifacts (ADRs, C4 diagrams) | No intermediate artifacts |

### Key Differentiators

1. **TDD agents have built-in checkpoints**: The commit cycle ensures no work is lost. Every GREEN state is committed. Research has no equivalent.
2. **TDD agents have bounded scope**: Test budget (2x behaviors) limits how much work is done. Research sources (3+ per claim) scale with topic complexity.
3. **TDD agents have DES enforcement**: TIMEOUT_INSTRUCTION, phase validation, turn logging. Research bypasses DES entirely.
4. **TDD agents are local-only**: No web operations. Every turn produces local, durable changes. Research turns often produce ephemeral in-context knowledge only.

---

## Root Cause Candidate Evaluation

| # | Candidate | Verdict | Confidence | Evidence |
|---|-----------|---------|------------|----------|
| 1 | No output checkpoints | **CONFIRMED** | High | Agent workflow places all writing in Phase 4 (last phase). No intermediate writes. |
| 2 | No turn awareness | **CONFIRMED** | High | Zero mentions of turns/budget in agent or skills. DES validation bypassed for research. |
| 3 | Scope creep | **PARTIALLY CONFIRMED** | Medium | "5-12 sources per topic" is broad but bounded. However, "3+ per major claim" can explode with complex topics. No diminishing-returns detection. |
| 4 | No diminishing returns detection | **CONFIRMED** | High | Zero mentions of "diminishing returns", "saturation", or "enough" in any researcher file. Circuit breaker only for tool failures, not research depth. |
| 5 | No phased approach (like TDD) | **CONFIRMED** | High | Research phases are sequential but lack the checkpoint-commit pattern that makes TDD resilient to turn exhaustion. |
| 6 | maxTurns too low | **CONFIRMED** | High | 30 turns is insufficient for web-heavy workflows. DES config defines research at 35, but agent uses 30. Comparable agents with simpler workflows get 50. |
| 7 | Output format unclear | **REFUTED** | High | research-methodology.md provides a detailed template (lines 12-61). The format is clear; the problem is reaching Phase 4 to use it. |
| 8 | Web search is expensive | **CONFIRMED** | High | Each source verification chain costs 3-5 turns. 5 claims x 3 sources = 15-25 turns on verification alone, leaving 5-15 for everything else. |

---

## Proposed Solutions

### Ranked by Impact and Feasibility

#### Solution 1: Progressive Research Output with Write-As-You-Go (Impact: Critical, Effort: Medium)

**Addresses**: ROOT CAUSE A (no checkpoints), ROOT CAUSE B (partial -- forces awareness)

Restructure the researcher workflow to write findings incrementally:

**Phase 2 (Search and Gather)**: After every 2-3 sources found, append raw findings to the output file. Create the document skeleton immediately at Phase 2 start. Each finding is written with its sources as it is verified, not batched for Phase 4.

**Phase 3 (Verify and Cross-Reference)**: Update existing findings in-place with verification status. Add cross-reference notes directly.

**Phase 4 (Synthesize)**: Becomes a refinement phase -- the document already exists with all findings. Phase 4 adds executive summary, fills gaps section, polishes prose.

**Result**: Even if the agent exhausts turns at Phase 3, the output file contains all findings gathered so far. Knowledge is never lost.

**Implementation**: Modify `nWave/agents/nw-researcher.md` workflow section and `nWave/skills/researcher/research-methodology.md`.

---

#### Solution 2: Turn Budget Awareness for Research (Impact: High, Effort: Low)

**Addresses**: ROOT CAUSE B (no turn awareness), ROOT CAUSE D (insufficient budget)

Add a TIMEOUT_INSTRUCTION-equivalent section to the researcher agent definition:

```markdown
## Turn Budget Management

You have approximately 30 turns. Plan your research accordingly.

**Checkpoints**:
- Turn 1-3: Load skills, clarify scope, create output file skeleton
- Turn 4-15: Search and gather sources (write each finding as you go)
- Turn 16-22: Cross-reference and verify (update findings in-place)
- Turn 23-28: Synthesize -- write executive summary, gaps, metadata
- Turn 29-30: Final quality check and close

**If approaching turn 20 without having started writing**: STOP gathering
immediately. Write everything you have. Partial research with documented
gaps is infinitely more valuable than no output.

**Early exit protocol**: If you must stop early, ensure the output file
exists with all findings gathered so far, clearly marked with verification
status (verified/unverified/partial).
```

**Implementation**: Add section to `nWave/agents/nw-researcher.md`.

---

#### Solution 3: Adaptive Quality Standards (Impact: High, Effort: Medium)

**Addresses**: ROOT CAUSE C (absolute standards), ROOT CAUSE D (budget pressure)

Introduce tiered research quality based on scope:

```markdown
## Quality Tier Selection

Before starting Phase 2, estimate the topic scope and select a tier:

| Tier | Claims | Sources/Claim | Total Sources | Suitable Turn Budget |
|------|--------|---------------|---------------|---------------------|
| Quick | 1-3 | 2 | 4-6 | 15-20 turns |
| Standard | 3-5 | 3 | 9-15 | 25-35 turns |
| Deep | 5-10 | 3+ | 15-30 | 40-50 turns |

If the topic requires Deep tier but your budget is Standard, explicitly
narrow the scope: "Researching X within the context of Y only. Out of
scope: Z."
```

**Implementation**: Modify `nWave/agents/nw-researcher.md` and `nWave/skills/researcher/research-methodology.md`.

---

#### Solution 4: Increase maxTurns to Match Workflow Demands (Impact: Medium, Effort: Trivial)

**Addresses**: ROOT CAUSE D (insufficient budget)

Change `maxTurns: 30` to `maxTurns: 50` in `nWave/agents/nw-researcher.md:6`.

**Rationale**: The DES config already defines `research: 35` as a higher tier than standard. The researcher has web-dependent operations making each turn more expensive than local-only agents. 50 turns matches software-crafter and solution-architect, which also produce complex deliverables.

**Caution**: This alone is necessary but insufficient. Without Solutions 1-3, increasing turns merely delays the same failure for complex topics and wastes more tokens before the same outcome. This solution should be implemented alongside progressive output.

---

#### Solution 5: Diminishing Returns Detection (Impact: Medium, Effort: Medium)

**Addresses**: ROOT CAUSE C (unbounded searching)

Add to the researcher's methodology:

```markdown
## Diminishing Returns Rule

After finding sources, check:
1. Is this source saying the same thing as 2+ sources already gathered?
   -> Stop searching this claim. Move to next claim or to writing.
2. Have you spent 3+ turns searching for a specific claim with < 2 sources?
   -> Document as Knowledge Gap. Move to next claim.
3. Are you past turn 15 and still in Phase 2?
   -> Transition to Phase 3 immediately with what you have.
```

**Implementation**: Add to `nWave/skills/researcher/research-methodology.md`.

---

#### Solution 6: Research-Specific DES Integration (Impact: Medium, Effort: High)

**Addresses**: ROOT CAUSE B (no DES enforcement for research)

Extend the DES system to support non-TDD workflows:
- Add research-specific phase validation (SCOPE, GATHER, VERIFY, WRITE)
- Create a research-specific TIMEOUT_INSTRUCTION template
- Enable phase logging for research tasks
- Add turn tracking for cross-wave agents

**Caution**: High effort. The current DES architecture is tightly coupled to TDD workflow. This is a long-term improvement, not a quick fix.

**Implementation**: Requires changes to `src/des/domain/timeout_instruction_template.py`, `src/des/application/orchestrator.py`, and new research-specific domain objects.

---

## Solution Priority Matrix

| Solution | Impact | Effort | Priority | Dependencies |
|----------|--------|--------|----------|-------------|
| S1: Progressive output | Critical | Medium | P0 | None |
| S2: Turn budget awareness | High | Low | P0 | None |
| S4: Increase maxTurns to 50 | Medium | Trivial | P0 | None |
| S3: Adaptive quality standards | High | Medium | P1 | S2 (needs budget context) |
| S5: Diminishing returns detection | Medium | Medium | P1 | S1 (progressive output enables this) |
| S6: Research-specific DES | Medium | High | P2 | S1, S2 (validate pattern first) |

**Recommended implementation order**: S4 + S2 + S1 (immediate sprint), then S3 + S5 (next sprint), then S6 (backlog).

---

## Key Insight: The Structural Asymmetry

The fundamental issue is a structural asymmetry between TDD and research workflows:

**TDD** produces durable artifacts at each step (committed code). If the agent stops at any point after GREEN, the work is preserved. The workflow is inherently checkpoint-friendly.

**Research** produces ephemeral in-context knowledge until the final write. If the agent stops before Phase 4, ALL knowledge is lost. The workflow is inherently checkpoint-hostile.

The nWave framework was designed around TDD-like workflows where the "commit early, commit often" pattern naturally prevents turn exhaustion from losing work. Research is the first workflow type where this assumption fails, and the framework has no mechanism to compensate.

This is not just a researcher problem. Any future agent with a "gather-then-produce" pattern (e.g., a data analysis agent, an audit agent) will face the same structural issue. The fix should be generalizable.

---

## Files Examined

| File | Purpose |
|------|---------|
| `nWave/agents/nw-researcher.md` | Agent definition, maxTurns, workflow |
| `nWave/tasks/nw/research.md` | Command definition, orchestration |
| `nWave/skills/researcher/research-methodology.md` | Output template, quality standards |
| `nWave/skills/researcher/source-verification.md` | Source validation methodology |
| `nWave/skills/researcher/authoritative-sources.md` | Domain authority database |
| `nWave/skills/researcher/operational-safety.md` | Tool safety, error recovery |
| `nWave/agents/nw-software-crafter.md` | Comparison: TDD workflow, turn management |
| `nWave/agents/nw-solution-architect.md` | Comparison: design workflow |
| `nWave/agents/nw-acceptance-designer.md` | Comparison: 30-turn agent |
| `nWave/agents/nw-troubleshooter.md` | Comparison: 30-turn cross-wave agent |
| `src/des/config/des_defaults.yaml` | Turn limit tiers |
| `src/des/domain/timeout_instruction_template.py` | TIMEOUT_INSTRUCTION (TDD-specific) |
| `src/des/application/orchestrator.py` | DES orchestrator, research bypass |
| `src/des/application/validator.py` | Mandatory section validation |
| `nWave/tasks/nw/execute.md` | DES template with TIMEOUT_INSTRUCTION |
