This is original teaching material built around the supplied outline. It is not authored by Theo or MEGA. Patch Desk, our fictional repository assistant, now needs a reliable way to find facts after the conversation that first uncovered them has ended.
Learning goals
- Organize files by the questions they answer and the authority they carry.
- Distinguish a style guide, specification, task, library, and research note.
- Keep useful knowledge current without making every document mandatory context.
In his public context-file audit, Theo identifies duplicated configuration and misleading architecture guidance. That motivates this lesson's original distinction between authoritative files and explanatory notes. Automatic captions, around 4:30–6:30.
A knowledge system must answer a question
A large folder of Markdown is not automatically a useful knowledge system. Start with the recurring questions: how do I run the project, what behavior must remain true, what decision did we make, and what evidence supports it? Each question needs an authoritative location and a way to discover it.
In Patch Desk, package.json owns executable script names, the contributing guide explains when humans use those scripts, and a decision note records why documentation validation is separate from application tests. These files overlap in subject but have different jobs. Copying the complete script configuration into all three creates several versions of the same truth.
The original design rule for this lesson is to store facts near the thing that owns them and link from explanatory documents. A change to a script then requires updating the guide that describes its usage, not searching for ten independently maintained script inventories. The cost of maintaining knowledge is part of its design, not a cleanup step after the library becomes confusing.
Separate the five document roles
A style guide describes conventions that help a reader or contributor make consistent choices. It might prefer short command examples or require explanations of non-obvious prerequisites. It should distinguish a genuine project constraint from a preference. “The documentation checker parses fenced shell blocks” is a technical fact; “prefer one command per block” may be a style preference.
A specification defines observable behavior. For a documentation checker, the specification might say that links to missing local files fail validation and external links are not fetched during offline checks. This tells an agent what a change must preserve. A task saying “improve links” is inadequate without that boundary, because an eager implementation might add network calls to a deliberately offline checker.
A task names a bounded change to current behavior. It should reference the specification, state the defect or desired outcome, and identify evidence that will demonstrate completion. A task is not the permanent location for all project knowledge. Once completed, durable decisions should live where the next task can find them.
A library collects reusable procedures, examples, and references. The Agent Skills specification's supporting directories offer one concrete packaging model: instructions can point to scripts, references, and assets. The useful principle is selective loading. The agent should discover the relevant procedure rather than receive every reference on every task.
Research records what was examined, when, what it supports, and what remains uncertain. A research note should not say “the deployment command works” when it merely found documentation describing the command. Separate a source's statement, your interpretation, and an observation from a run you actually performed. That separation prevents guesses from hardening into project policy.
Retrieval is a design decision
There are several ways to find knowledge: filenames, a short index, text search, structured queries, or semantic retrieval. Choose based on actual retrieval failures. For a small repository, predictable filenames and search may solve the problem more simply than a separate indexing service.
Anthropic describes using lightweight references to retrieve relevant material as work proceeds in its context engineering discussion. Apply that narrowly here: Patch Desk begins with an index of authoritative files, then reads the needed sections. A pointer does not guarantee successful retrieval; the tool still needs access and a result that identifies where the information came from.
If you add a summary, record its scope and source. “All validation is offline” may be too broad if only the documentation checker is offline. A more precise entry is “the documentation check does not fetch remote links; see checker specification.” The narrower statement is easier to verify and less likely to mislead a future task.
Worked example: repair the knowledge trail
Imagine Patch Desk finds three conflicting notes: a setup guide says npm test, a recent task says npm run check, and an old research file says the project uses a different package manager. The current configuration defines check. Do not resolve the conflict by choosing the newest-looking prose alone. Inspect the configuration and the scope of each note.
Create this original illustrative layout:
docs/start-here.md purpose and authoritative pointers
docs/contributing.md current contributor workflow
docs/specs/doc-checker.md accepted and rejected behavior
docs/decisions/offline.md reason for offline validation
research/command-audit.md examined files and remaining uncertaintyThe index can be small:
To run checks: read package.json and docs/contributing.md.
To change validation behavior: read docs/specs/doc-checker.md.
To understand the offline constraint: read docs/decisions/offline.md.
Historical command audit: research/command-audit.md; recheck live state.The reasoned result is a traceable path from question to evidence. The task note can link to the corrected guide and say the mismatch was repaired. The old research can remain historical if clearly dated; silently rewriting it as though it always described the current state would destroy useful provenance.
For shared work, Git provides a concrete way to inspect the edits and preserve history. T3 Code's source-control documentation describes reviewing changes and source-control operations in the control surface. Use the diff to check that a knowledge repair did not accidentally modify application behavior.
Practice
Choose one recurring project question that currently requires searching several conversations. Create an index entry and a single authoritative explanation, with links to the underlying source of truth. Keep historical evidence separate from current instructions. Ask a fresh reader to answer the question using only your new entry.
Acceptance criteria: the reader finds the right source without prior chat context; the answer is correct for the current checkout; the explanation distinguishes historical and current facts; and the maintenance owner is clear. If the reader cannot identify which file wins a conflict, revise the authority relationship rather than adding more prose.
A strong submission includes one stale statement you found and explains how you corrected or labeled it. It also explains what should trigger the next review: a configuration change, a release, or a broken verification check. “We will keep it up to date” is not a trigger someone can observe.
Check your understanding
- Should a research note become policy automatically? No. Evidence, interpretation, and an accepted decision are separate states.
- Does semantic search remove the need for authority? No. A relevant result can still be stale or subordinate to another source.
- What makes a specification useful to an agent? Observable behavior and constraints that can guide and verify a change.