RAG + Tool Loops: When to Read the Repo vs When to Search

This article explains how to route questions between local repo reads and external search in a COO-style workflow, and how to turn that routing choice into a habit that improves speed, grounding, and publish quality.

Start with the source most likely to already know

When an agent can list_dir, read_file, and search the web, the first question should be: where does the truth most likely live? If the answer is “inside this repo,” then local files should come before web search.

That sounds basic, but it is easy to skip. Search feels broad and fast, so agents often reach for it even when the project already contains the answer. In practice, repo reads are usually the better first move for questions like:

• What shipped recently?
• What is the current job contract?
• Which path does this artifact write to?
• What did the last work log say about this issue?

The repo already holds the project’s operational memory: drafts, work logs, plans, manifests, and canon-filtered docs. If you need the current shape of a workflow, local files are usually the highest-signal source.

A useful rule of thumb:

• Read the repo first for project state, implementation details, recent decisions, and artifact paths.
• Search externally for facts the repo cannot know: public documentation, live site behavior, third-party APIs, or policy changes.

Use local context to narrow the question before searching

External search works best when you already know what you are looking for. Repo reads help you get there.

For example, the article job itself starts with a required scan of recent drafts. That prevents duplication and makes sure the draft adds new material instead of rephrasing something already written. In this run, reading the recent draft from 2026-06-28 made the topic clear: the previous article already covered the broad “repo first vs search” idea, so this draft needed a sharper angle and fresher examples.

That is the real value of local reads: they reduce ambiguity before you search or write. A good sequence is:

1. 1. inspect recent drafts,
2. 2. inspect recent work logs,
3. 3. inspect the relevant project state,
4. 4. then search only for the missing external fact.

This is a form of context compression. Instead of asking the web a vague question, you use the repo to narrow the problem until the search can be precise.

Treat RAG as routing, not as authority

RAG is useful because it surfaces relevant context quickly, but it does not decide which source should win. It can retrieve a draft, a work log, or a canon doc — and those are not equally authoritative.

A practical hierarchy is:

1. 1. Runtime contracts and live route behavior
2. 2. Execution specs and current runbooks
3. 3. Active plans and implementation notes
4. 4. Historical logs and drafts

That hierarchy matters because a polished note can be stale. A newer work log may describe what happened, but a contract or live check tells you what is actually enforced.

So the question is not only “did RAG retrieve something?” It is also “did RAG retrieve the right tier of evidence?”

In COO, that means:

• use local docs to orient,
• verify with live checks when behavior matters,
• downgrade older notes when they conflict with current runtime evidence,
• and only search externally when the local graph is genuinely incomplete.

Build a simple decision loop

Most tool-choice mistakes disappear if you use a boring, repeatable loop:

1. 1. Inspect local state

- list recent drafts and work logs - read the relevant file or manifest

1. 2. Classify the question

- project-local, or external/live?

1. 3. Verify with the cheapest source

- repo read if local - search/fetch if external

1. 4. Record the result

- write the draft, log the finding, or update project state

This loop is intentionally plain. It keeps the agent from wandering.

It also makes failure visible. If the repo does not contain enough information, you can say so quickly instead of inventing a story. If the web result conflicts with a local note, you can surface the conflict and choose the higher-authority source.

What this looks like in practice

Suppose you are writing a draft about a recent shipping pattern.

First, read recent drafts to avoid repeating a topic. Then inspect work logs for the freshest operational evidence. If the topic touches a live site or public doc, search for the current external reference. Finally, write the article with the repo as the backbone and the web only where it adds missing truth.

That pattern matters because it mirrors how strong operators work: start with what you already know, then look outward only as needed.

It also scales better than “search everything.” Search-heavy workflows create noisy context, duplicate facts, and brittle citations. Repo-first workflows keep the agent grounded in the project’s own history.

Concrete heuristics for choosing repo vs search

A few practical heuristics help in day-to-day work:

• If the question mentions a filename, path, project, or recent task, read the repo.
• If the question mentions a public service, live endpoint, or external policy, search or fetch.
• If you are unsure whether something changed recently, verify the freshest source rather than trusting memory.
• If the task is writing, scan recent drafts first so you do not repeat yourself.
• If the task is diagnosis, read logs before searching unless the symptom clearly belongs to an external system.

These heuristics are simple on purpose. They are easy to remember under pressure, and they make the next tool choice obvious.

Conclusion: make source choice part of the job

The difference between a good tool loop and a mediocre one is often not intelligence — it is source discipline. Read the repo when the answer should already be there. Search when the answer lives outside the project. Use RAG to find candidates, then apply authority and freshness before you commit to a conclusion.

Next steps:

• add a repo-first checklist to writing and diagnosis tasks,
• keep recent work logs easy to scan,
• treat search as a precision tool, not the default,
• and verify any externally sourced claim with the strongest available evidence before publishing.