# ADR-0019: No Context Augmentation on Read — read+grep Is Sufficient

**Status:** Accepted  
**Date:** 2026-05-16

## Problem

The agent overwhelmingly uses `read` (full-file) and `bash` (grep/cat) for code navigation, ignoring specialized code-intel tools (`inspect_code`, `find_symbol`). We investigated whether augmenting `read` results with tree-sitter outlines would improve efficiency.

Candidate approaches evaluated:

- **Append outline** to `read` results for large source files (à la pi-lens's LSP injection on edit)
- **Truncate + outline** — force partial reads with structure hints
- **Nudge messages** — append "use inspect_code next time" tips
- **Context injection** (ctx++ / GitNexus-style) — proactive graph-based context retrieval

## Decision

**Do nothing.** Keep `read` and `bash` as-is. Rely on system prompt guidance for tool preference. Do not adopt ctx++, GitNexus, Codebase Memory, or similar context augmentation libraries.

## Evidence (empirical, from session analytics)

Analysis of **9,647 read results** and **34,496 total tool results** across all historical sessions:

| Metric                           | Value                               |
| -------------------------------- | ----------------------------------- |
| Total read token spend           | 14.3M tokens                        |
| Source code reads                | 4,527 (48%) → 7.8M tokens           |
| Large source reads (>200 lines)  | 1,541 (16.5%) → 5.6M tokens (39%)   |
| Partial reads (offset/limit)     | **0**                               |
| `inspect_code` calls             | **0**                               |
| `find_symbol` calls              | **0**                               |
| `bash` calls                     | 16,215 (47% of all tool use)        |
| Sessions completing successfully | Normal — no evidence of degradation |

### Key findings

1. **The agent never uses partial reads.** Zero offset/limit usage across 9,647 read calls. The model's strategy is: read the whole file, grep what you need from bash.

2. **Code-intel tools have zero adoption.** Despite being registered with descriptions, promptSnippets, and promptGuidelines. The legacy names (`get_function`/`file_skeleton`) had 291 uses before the rename — adoption dropped to zero after.

3. **Appending outlines to full reads is redundant.** When you already see all 300 lines, a 30-line structural summary adds nothing the model can't already observe. Cost: +185K tokens (+1.3%) for zero information gain.

4. **The break-even math doesn't work.** An outline costs ~120 tokens/read. The average large-file read costs ~3,661 tokens. The outline would need to prevent 1 re-read per 30 augmented reads to break even — but there's no mechanism by which a redundant summary prevents re-reads of content you already have in context.

5. **"Nudge" messages are prompt engineering with no proven effect.** No research demonstrates that appending tool-preference hints to tool results changes an LLM's subsequent tool selection behavior. This is woo-woo.

## Alternatives Rejected

### ctx++ / Codebase Memory / GitNexus-style graph retrieval

These systems build semantic graphs of codebases and proactively inject "relevant context" before tool calls. Rejected because:

- **No evidence of need.** The agent completes tasks with read+grep. Sessions don't fail due to missing context.
- **Token cost is additive, not substitutive.** Graph context gets injected _in addition to_ what the model reads, not instead of it. Net token spend increases.
- **Complexity vs. payoff.** Maintaining a semantic graph (embeddings, chunking, reindexing on every commit) for marginal context improvement is not justified by the data.
- **The 291→0 drop** after renaming tools proves that adoption is prompt/habit-driven, not capability-driven. A fancier retrieval system won't fix a behavioral problem.

### Outline append on `tool_result`

Rejected because full-file reads make the outline redundant. Would only help if the model used partial reads — which it doesn't.

### Truncated reads (force outline-only for large files)

Rejected as too aggressive. Would break existing working behavior. The model reads full files, edits them successfully, and moves on. Forcing a two-step workflow (outline → targeted read) adds latency and tool calls for no proven quality gain.

## What We Did Instead

Added guidance to `SYSTEM.md`:

- "Read efficiently — use `inspect_code` and `find_symbol`" in Principles
- Explicit tool preference ordering in Workflow step 2 (inspect_code → find_symbol → LSP → ast_grep → bash/grep as fallback)

This is low-cost, non-invasive, and testable. If tool usage shifts in future sessions, we'll know.

## Lessons

- **Measure before building.** 30 minutes of DuckDB analysis prevented building a feature with +1.3% token cost and 0% benefit.
- **Behavioral problems need behavioral solutions.** The model ignores tools because it has ingrained habits, not because the tools are hard to find. Injection/augmentation doesn't fix habits.
- **Simple tools win.** `read` has trivial semantics (path → content). `bash grep` has trivial semantics (pattern → matches). The model trusts what it understands. Complex tools with multiple modes and optional args get ignored.
- **Renaming tools kills adoption.** The 291→0 cliff after `get_function`→`inspect_code` is a cautionary tale. If it ain't broke, don't rename it.
