[Phase 2.5] ReactAgent wastes 30% of iteration budget on redundant file exploration

[frankbria]

Problem

The ReactAgent spends 9 out of 30 iterations (30%) reading files before creating its first file. On a 30-iteration budget where each file create + lint-fix cycle takes 3-5 iterations, this leaves only enough budget for 4-7 files — insufficient for most tasks.

Observed Behavior

Running codeframe work start <id> --execute --engine react --verbose on cf-test:

Iteration	Tool	Purpose
1	list_files	Discover project structure
2-6	read_file (x5)	Read individual files
7	search_codebase	Search for patterns
8	list_files	Re-discover structure
9	read_file	Read one more file
10	create_file	First write

Root Causes

1. Initial user message mandates reading (react_agent.py:237-238)

"Start by reading relevant files to understand the current "
"codebase, then make the necessary changes."

This creates a strong bias toward exploration before implementation.

2. System prompt includes file PATHS but not file CONTENTS (react_agent.py:509-524)

for fi in context.file_tree[:50]:
    tree_lines.append(f"  {fi.path}")  # PATHS ONLY, NO CONTENT

The agent sees the file tree but must call read_file tool to see what's actually in each file.

3. ContextLoader loads file contents but they're discarded (context.py:476-542 vs react_agent.py:497-551)

ContextLoader._load_file_contents() identifies relevant files and loads their content into context.loaded_files. But _build_system_prompt() never converts loaded_files into a prompt section. The prepared content is wasted.

4. System rules reinforce reading (react_agent.py:59-89)

- ALWAYS read a file before editing it. Never assume file contents.

Combined with the initial message, this creates a double mandate for exploration.

Proposed Fix

Three complementary changes:

1. Include loaded file contents in system prompt: Add a "## Relevant Source Files" section in _build_system_prompt() using the already-loaded context.loaded_files. The ContextLoader already does the relevance scoring and token budgeting — the data just needs to be surfaced.

2. Revise initial user message: Change from "Start by reading relevant files" to something like "Implement the task. The system prompt includes relevant context. Use tools to explore further only if needed."

3. Soften the "always read before editing" rule: On small projects where context is pre-loaded, the agent doesn't need to re-read files it's about to create (which don't exist yet).

Expected Improvement

With relevant file contents pre-loaded:

• Agent should start writing by iteration 2-3 (instead of 10)
• Gains 7+ iterations for actual implementation
• Could complete 2-3 more files per task

Files

• codeframe/core/react_agent.py — _build_system_prompt() (line 497), initial message (line 232), rules (line 59)
• codeframe/core/context.py — _load_file_contents() (line 476), TaskContext.loaded_files (line 119)

[traycerai]

Plan

Observations

The ReactAgent currently loads relevant file contents via ContextLoader._load_file_contents() into context.loaded_files, but these contents are never surfaced to the LLM. The _build_system_prompt() method only includes file paths (line 512), forcing the agent to spend iterations reading files it already has access to. The base rule "ALWAYS read a file before editing it" (line 68) further reinforces this exploration-first behavior, wasting ~30% of the iteration budget before any implementation begins.

Approach

The fix leverages the already-loaded file contents by including them in the system prompt, eliminating redundant file reads. Since TaskContext.to_prompt_context() already formats loaded files correctly, we'll integrate this into _build_system_prompt(). The "always read before editing" rule will be softened to acknowledge pre-loaded context, allowing the agent to start implementation immediately when relevant files are already available. No initial user message changes are needed since the current implementation starts with an empty messages list.

Implementation Steps

1. Include Loaded File Contents in System Prompt

File: file:codeframe/core/react_agent.py

Modify the _build_system_prompt() method (lines 488-542) to include loaded file contents:

• After Layer 2 (file tree section, lines 509-515), add a new section for loaded file contents
• Check if context.loaded_files is not empty
• If files are loaded, add a "## Relevant Source Files" section
• For each file in context.loaded_files:
  • Add a subsection with the file path as a heading (e.g., ### {file.path})
  • Include the file content in a code block with appropriate syntax highlighting
  • Add a blank line between files for readability
• This mirrors the implementation in TaskContext.to_prompt_context() (lines 225-232) but integrates it into the 3-layer prompt structure

Example structure:

Layer 1: Base rules
Layer 2: Preferences, tech stack, file tree
  ## Relevant Source Files (NEW)
  ### path/to/file1.py

```

path/to/file2.py

<file content>

Layer 3: Task info, PRD, blockers

### 2. Update Base Rules to Acknowledge Pre-loaded Context

**File:** `file:codeframe/core/react_agent.py`

Modify the `_LAYER_1_RULES` constant (lines 60-90) to soften the "always read before editing" rule:

- Locate the rule at line 68: `"ALWAYS read a file before editing it. Never assume file contents."`
- Replace with a context-aware version:
  - `"Read files before editing them unless their contents are already provided in the 'Relevant Source Files' section above. Never assume file contents that aren't shown."`
- This allows the agent to skip reading files that are already loaded while maintaining safety for files not in context
- Keep the rule at line 74: `"Never edit_file on a file you haven't read in this session."` but clarify it means "haven't seen in this session (either via read_file tool OR in the Relevant Source Files section)"

### 3. Update Tests for System Prompt

**File:** `file:tests/core/test_react_agent.py`

Update the `TestSystemPrompt.test_system_prompt_contains_all_3_layers` test (lines 211-246):

- Add loaded files to the `mock_context` fixture
- Create sample `FileContent` objects with test file paths and content
- Set `mock_context.loaded_files` to include these files
- Add assertions to verify the system prompt contains:
  - The "## Relevant Source Files" section header
  - The file paths from loaded files
  - Sample content from the loaded files
- Verify the updated rule text about pre-loaded context

### 4. Verify Token Budget Handling

**File:** `file:codeframe/core/context.py`

Review the `_load_file_contents()` method (lines 476-505) to ensure:

- The token budget calculation (lines 485-493) accounts for the loaded file contents
- The `context.total_tokens` is updated correctly (line 504)
- Files are loaded in relevance order (line 496) until budget is exhausted
- This ensures the system prompt doesn't exceed model context limits

No changes needed here - just verification that the existing implementation correctly manages token budgets.

### 5. Update Documentation

**File:** `file:codeframe/core/react_agent.py`

Update the docstring for `_build_system_prompt()` (lines 488-494):

- Expand Layer 2 description from "Project preferences + tech stack + file tree summary" to "Project preferences + tech stack + file tree summary + loaded file contents"
- Add a note explaining that loaded files are included to reduce redundant read_file calls
- Document the token budget consideration

## Expected Impact

```mermaid
sequenceDiagram
    participant Agent as ReactAgent
    participant Context as ContextLoader
    participant LLM as LLM Provider
    
    Note over Agent,LLM: BEFORE (Current Implementation)
    Agent->>Context: load(task_id)
    Context->>Context: _load_file_contents()
    Note over Context: Loads files but discards
    Context-->>Agent: context (files not in prompt)
    Agent->>Agent: _build_system_prompt()
    Note over Agent: Only file paths included
    Agent->>LLM: Iteration 1-9: read_file calls
    Note over LLM: Wasting 30% of budget
    Agent->>LLM: Iteration 10+: create_file
    
    Note over Agent,LLM: AFTER (With Fix)
    Agent->>Context: load(task_id)
    Context->>Context: _load_file_contents()
    Note over Context: Loads relevant files
    Context-->>Agent: context (with loaded_files)
    Agent->>Agent: _build_system_prompt()
    Note over Agent: Includes file contents
    Agent->>LLM: Iteration 1-2: create_file
    Note over LLM: Starts implementation immediately
    Agent->>LLM: Iteration 3+: more implementation

Performance Improvement:

• Agent should start writing by iteration 1-2 (instead of iteration 10)
• Gains 7-8 iterations for actual implementation
• Could complete 2-3 more files per task within the 30-iteration budget
• Reduces wasted exploration from 30% to ~5-10%

Import In IDE

🤖 Prompt for AI Agents

## Observations

The ReactAgent currently loads relevant file contents via `ContextLoader._load_file_contents()` into `context.loaded_files`, but these contents are never surfaced to the LLM. The `_build_system_prompt()` method only includes file paths (line 512), forcing the agent to spend iterations reading files it already has access to. The base rule "ALWAYS read a file before editing it" (line 68) further reinforces this exploration-first behavior, wasting ~30% of the iteration budget before any implementation begins.

## Approach

The fix leverages the already-loaded file contents by including them in the system prompt, eliminating redundant file reads. Since `TaskContext.to_prompt_context()` already formats loaded files correctly, we'll integrate this into `_build_system_prompt()`. The "always read before editing" rule will be softened to acknowledge pre-loaded context, allowing the agent to start implementation immediately when relevant files are already available. No initial user message changes are needed since the current implementation starts with an empty messages list.

## Implementation Steps

### 1. Include Loaded File Contents in System Prompt

**File:** `file:codeframe/core/react_agent.py`

Modify the `_build_system_prompt()` method (lines 488-542) to include loaded file contents:

- After Layer 2 (file tree section, lines 509-515), add a new section for loaded file contents
- Check if `context.loaded_files` is not empty
- If files are loaded, add a "## Relevant Source Files" section
- For each file in `context.loaded_files`:
  - Add a subsection with the file path as a heading (e.g., `### {file.path}`)
  - Include the file content in a code block with appropriate syntax highlighting
  - Add a blank line between files for readability
- This mirrors the implementation in `TaskContext.to_prompt_context()` (lines 225-232) but integrates it into the 3-layer prompt structure

**Example structure:**
```
Layer 1: Base rules
Layer 2: Preferences, tech stack, file tree
  ## Relevant Source Files (NEW)
  ### path/to/file1.py
  ```
  <file content>
  ```
  
  ### path/to/file2.py
  ```
  <file content>
  ```
Layer 3: Task info, PRD, blockers
```

### 2. Update Base Rules to Acknowledge Pre-loaded Context

**File:** `file:codeframe/core/react_agent.py`

Modify the `_LAYER_1_RULES` constant (lines 60-90) to soften the "always read before editing" rule:

- Locate the rule at line 68: `"ALWAYS read a file before editing it. Never assume file contents."`
- Replace with a context-aware version:
  - `"Read files before editing them unless their contents are already provided in the 'Relevant Source Files' section above. Never assume file contents that aren't shown."`
- This allows the agent to skip reading files that are already loaded while maintaining safety for files not in context
- Keep the rule at line 74: `"Never edit_file on a file you haven't read in this session."` but clarify it means "haven't seen in this session (either via read_file tool OR in the Relevant Source Files section)"

### 3. Update Tests for System Prompt

**File:** `file:tests/core/test_react_agent.py`

Update the `TestSystemPrompt.test_system_prompt_contains_all_3_layers` test (lines 211-246):

- Add loaded files to the `mock_context` fixture
- Create sample `FileContent` objects with test file paths and content
- Set `mock_context.loaded_files` to include these files
- Add assertions to verify the system prompt contains:
  - The "## Relevant Source Files" section header
  - The file paths from loaded files
  - Sample content from the loaded files
- Verify the updated rule text about pre-loaded context

### 4. Verify Token Budget Handling

**File:** `file:codeframe/core/context.py`

Review the `_load_file_contents()` method (lines 476-505) to ensure:

- The token budget calculation (lines 485-493) accounts for the loaded file contents
- The `context.total_tokens` is updated correctly (line 504)
- Files are loaded in relevance order (line 496) until budget is exhausted
- This ensures the system prompt doesn't exceed model context limits

No changes needed here - just verification that the existing implementation correctly manages token budgets.

### 5. Update Documentation

**File:** `file:codeframe/core/react_agent.py`

Update the docstring for `_build_system_prompt()` (lines 488-494):

- Expand Layer 2 description from "Project preferences + tech stack + file tree summary" to "Project preferences + tech stack + file tree summary + loaded file contents"
- Add a note explaining that loaded files are included to reduce redundant read_file calls
- Document the token budget consideration

## Expected Impact

```mermaid
sequenceDiagram
    participant Agent as ReactAgent
    participant Context as ContextLoader
    participant LLM as LLM Provider
    
    Note over Agent,LLM: BEFORE (Current Implementation)
    Agent->>Context: load(task_id)
    Context->>Context: _load_file_contents()
    Note over Context: Loads files but discards
    Context-->>Agent: context (files not in prompt)
    Agent->>Agent: _build_system_prompt()
    Note over Agent: Only file paths included
    Agent->>LLM: Iteration 1-9: read_file calls
    Note over LLM: Wasting 30% of budget
    Agent->>LLM: Iteration 10+: create_file
    
    Note over Agent,LLM: AFTER (With Fix)
    Agent->>Context: load(task_id)
    Context->>Context: _load_file_contents()
    Note over Context: Loads relevant files
    Context-->>Agent: context (with loaded_files)
    Agent->>Agent: _build_system_prompt()
    Note over Agent: Includes file contents
    Agent->>LLM: Iteration 1-2: create_file
    Note over LLM: Starts implementation immediately
    Agent->>LLM: Iteration 3+: more implementation
```

**Performance Improvement:**
- Agent should start writing by iteration 1-2 (instead of iteration 10)
- Gains 7-8 iterations for actual implementation
- Could complete 2-3 more files per task within the 30-iteration budget
- Reduces wasted exploration from 30% to ~5-10%

---

Execution Information

Branch: main
Commit: e04112c

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#342 - feat: agent execution resilience - file conflicts, verification recovery, observability [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#358 - feat: read-only agent tools (read_file, list_files, search_codebase) [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]
#370 - feat: token budget tracking and message compaction for ReactAgent (#352) [merged]

---

📝 Issue Planner

<sub>Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.</sub>

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!