Primary and secondary sources
Every piece of context is one or the other, and knowing which one you are handing the agent tells you how much to trust the answer.
Borrow the distinction from historians — it is startlingly useful here.
- A primary source is the thing itself: the actual source file, the real schema, the raw log, the failing test output, the actual API response.
- A secondary source is an account of a primary: a README, a summary the agent wrote earlier, a design doc, a comment, your own recollection.
The trade-off
| Primary | Secondary | |
|---|---|---|
| Accuracy | Complete and current by definition | Lossy; can be stale or simply wrong |
| Token cost | High — often thousands per file | Low — tens to hundreds |
| Good for | Making a change; verifying a claim | Orientation; deciding which primary to open |
Neither is correct in general. The skill is matching the source type to the job.
Three working rules
- Orient with secondaries, act on primaries. Let the agent read the README to find the right module, then read the actual module before editing it. Never let it edit a file it has only read about.
- Verify claims against primaries. When an agent tells you how something works, the check is the file, not a second agent's opinion of the file. This is the concrete practice behind Lesson 2.5.
- Treat agent-written summaries as secondaries forever. A summary the agent produced ten turns ago has the same status as a stale doc: useful for navigation, not evidence. It is especially dangerous because it looks like context rather than like a claim.
Watch out
Compaction — where the harness summarises earlier history to free room — silently converts every primary in your window into a secondary. Files the agent genuinely read become a paragraph describing them. This is why work after an autocompact so often goes subtly wrong, and why Module 06 treats compaction as a last resort rather than a feature.
Documentation as a source-type problem
This reframes a common argument. A stale README is not merely unhelpful; it is a confident secondary source that will be believed. Given the choice, an agent will happily take your out-of-date docs over the code, because the docs are shorter and read more authoritatively.
Either keep docs accurate or make them explicitly provisional. Module 05 covers writing project briefs that point at primaries instead of restating them — which sidesteps the staleness problem entirely.
Try it
Find a doc in your repo that has drifted from the code. Ask a fresh agent a question whose true answer is in the code and whose wrong answer is in the doc. Watch which one it believes. Then fix the doc, or delete it.
Takeaways
- Orient with secondaries; make changes and verify claims against primaries.
- Anything the agent summarised is a secondary source from that moment on.
- Compaction turns primaries into secondaries silently — the main reason to prefer explicit handoffs.
Why is a stale README more dangerous to an agent than no README at all?
Because it is cheap, confident, and read first. With no README the agent has to open the code — a primary. With a stale one it gets a plausible, compact, wrong account and has no reason to look further. Wrong context beats missing context in cost every time.
Module 02 of this course ends here
The Next Steps goes under it: attention budgets you can measure, context poisoning, memory systems, compaction done deliberately, and very large inputs.
See what is in it →A course by Pieter Zandbergen