Contents
- 01The Builder's Starting Line
- 02Your Computer, Explained
- 03How Software Fits Together
- 04Start With the Work
- 05Build Your First Useful Tool
- 06Make Changes Safely
- 07Prompts Are Specifications
- 08Models Are Components
- 09Give Agents Jobs, Not Vibes
- 10Tools, APIs, and the Harness
- 11Truth Before Intelligence
- 12Patterns for Real Systems
- 13Approval Is a Feature
- 14Receipts or It Didn’t Happen
- 15Operate and Debug the Loop
- 16Design Your Own OS
- 17Make It Ready for Real Life
- 18Build and Evolve Your OS
Truth Before Intelligence
Context, memory, and state make capable models useful.
Context is not a prompt
A long prompt can explain a task, but it cannot maintain a business, product, or life. Durable context has owners, locations, timestamps, permissions, and a way to be corrected. It survives the current conversation and can be inspected by the next worker.
The practical question is not how much context the model can hold. It is which facts the task requires, where those facts come from, and how the system knows they are still true.
“A smarter model with stale context is still confidently working on the wrong world.”
Layers of truth
Different truths change at different speeds. Identity and operating principles are durable. Project state changes daily. Runtime status can change in seconds. A useful truth layer separates those categories so a timeless principle does not get buried in a log, and a live outage is not treated like permanent doctrine.
That means distinguishing knowledge and memory from task state, runtime connections, and proof. The source may be a document, database row, repository, external service, or live health check. What matters is that the system knows which kind of truth it is reading.
- Doctrine: durable identity, principles, and boundaries.
- Knowledge: researched or authored reference material.
- State: projects, tasks, decisions, and ownership.
- Runtime: what is connected and healthy now.
- Receipts: evidence of what happened.
Freshness and provenance
Every consequential fact should answer two questions: where did this come from, and when was it last verified? Provenance lets a worker distinguish a primary source from a summary. Freshness prevents yesterday’s deployment status or organization chart from masquerading as current truth.
When a fact is cheap to recheck and likely to drift, recheck it. When verification is expensive, label the age and uncertainty. Honest uncertainty is a feature because it gives the user a real decision instead of false confidence.
Case file
local recovery, stale public proof
A feature is working in a local checkout and a developer can produce a clean build. The last public repository workflow, however, is older and failed. A planning tracker cannot be queried because its authorization expired. An installed application may still be running a previous bundle.
A shallow assistant collapses these facts into one optimistic status: ‘the feature is fixed.’ A truth-aware system keeps the evidence planes separate. Local source and build receipts support a local-recovery claim. The stale workflow supports no current shared claim. The unavailable tracker is reported as unavailable rather than inferred. The installed app remains unverified until the shipping path runs and the behavior is observed there.
The front door can then give the user a useful answer: what recovered locally, what remains unshared, which external truth is unavailable, and what next action closes the highest-value proof gap. The system is not less intelligent for refusing to smooth over the contradiction; it is more operationally honest.
Decisions made
- 01Represent local, shared, live, and installed evidence as separate truth records.
- 02Attach timestamps, revisions, and sources to every status claim.
- 03Mark inaccessible systems as unknown rather than carrying forward their last known state.
- 04Route the next action from the first missing proof layer, not from the most reassuring evidence.
A truth layer earns trust by preserving disagreement between sources until the system can resolve it. A clean summary should clarify uncertainty, not erase it.
Memory needs forgetting
Saving everything produces a landfill, not memory. The system needs rules for promotion, correction, and expiry. A transient detail can stay in a task. A repeated preference may become durable memory. A superseded decision should remain traceable but stop routing current work.
Good memory reduces repeated explanation while preserving the user’s ability to inspect and change what the system believes.
Failure mode: confidently stale
The most dangerous agent failure is often not a wild hallucination. It is a reasonable answer built from an old fact: the wrong branch, a renamed service, a former job title, an expired token, or a plan that was replaced last week.
Add source, verification time, and truth class to the task packet. When the decision depends on live state, make the live check part of the work rather than an optional afterthought.
Context is a budget
More context is not automatically better context. Every model has a finite attention budget, and every irrelevant log, duplicate document, or stale decision competes with the instructions and evidence that matter. Context engineering is therefore a selection problem: assemble the smallest set of information that lets this worker make the next decision correctly.
The assembly pipeline should begin from the task, not from everything the system knows. Resolve the entities in the request. Retrieve candidate facts from the appropriate truth classes. Rank them by relevance, authority, and freshness. Remove duplicates and superseded records. Compress long material without erasing provenance. Finally, reserve space for tool observations and the worker’s output rather than filling the window before execution begins.
A good packet may include a durable operating rule, three current project facts, a handful of relevant files, the most recent failed receipt, and the acceptance criteria. It may deliberately exclude months of chat history. The measure is not how impressive the context bundle looks; it is whether the worker can identify the source, understand the current state, and act within the task boundary.
- Retrieve from the task outward instead of loading memory wholesale.
- Rank authority and freshness separately from semantic similarity.
- Preserve source pointers through summaries and compression.
- Leave capacity for new observations, exceptions, and recovery evidence.
Separate the truth planes
Knowledge, memory, task state, runtime state, and receipts answer different questions. Knowledge explains how something works. Memory records durable user preferences or prior decisions. Task state says what is expected now. Runtime state says what is connected or healthy at this moment. Receipts prove what actually occurred. Blending these planes creates subtle errors: a design document gets treated as deployed behavior, or a successful health check becomes proof that a feature meets its acceptance criteria.
Give each plane its own write policy and invalidation rule. A worker can propose durable memory, but the user or an explicit policy should approve promotion. Task events can update task state, but they should not rewrite doctrine. Runtime facts should expire quickly or be probed live. Receipts should be append-only evidence, even if a later receipt supersedes the conclusion.
The separation is operational, not philosophical. When a result is wrong, you can ask whether the system retrieved bad reference material, remembered an obsolete preference, misunderstood current task state, trusted stale runtime data, or accepted insufficient proof. Each diagnosis leads to a different repair.
Truth needs a schema
A source URL is not enough. Consequential records need an assertion, truth class, scope, owner, effective time, observation time, confidence, provenance, and invalidation rule. For repository truth, include the checkout and revision. For external service truth, include the account and probe. For a decision, include the alternatives considered and what supersedes it.
Confidence should describe the evidence, not the model’s feeling. ‘Observed from the production endpoint five minutes ago’ is stronger than ‘mentioned in a planning note last month.’ A derived fact should retain links to its inputs. A summary should state whether it is lossless structured extraction or interpretive compression.
This metadata lets the control layer answer more responsibly. It can prefer the canonical repository map over a stray path in chat, request a fresh probe when runtime evidence is expired, and disclose when a useful memory is historical rather than current. Intelligence becomes safer because the system can reason about the quality of its own inputs.
Across the business
What this looks like in other departments
The engineering principle stays the same; the workflow, risk, and proof change with the domain.
Customer support
Policy-aware answers
Distinguish durable product guidance from current account state, temporary incidents, historical conversations, and proof that the issue was resolved.
Finance
Source-aware forecasting
Keep actuals, assumptions, scenario models, approvals, and live cash positions separate so summaries disclose where each number came from.
People & HR
Current workforce truth
Separate policy, employee records, role history, active access, pending changes, and audit receipts with appropriate permissions and freshness.
Marketing
Defensible claims
Link product claims and customer stories to approved primary evidence, usage rights, effective dates, and the exact assets where they appear.
Technical deep dive
The context assembly pipeline
Build task-specific context that remains source-aware, current, and small enough for a worker to use well.
- 01ResolveIdentify the people, projects, repositories, services, time horizon, and proof surface named or implied by the request.
- 02RetrieveQuery the relevant truth planes with source-specific methods: structured state, semantic knowledge search, repository inspection, or live runtime probes.
- 03RankScore candidates by task relevance, source authority, freshness, scope match, and whether the record has been superseded.
- 04RefineDeduplicate, remove stale or conflicting views, compress large material, and preserve citations plus the reason each item was selected.
- 05InvalidateAssign expiry or recheck conditions, then update or supersede records when tool observations and receipts reveal a newer world state.
Reference schema
truth.id: stable record identifier truth.claim: atomic assertion + scope truth.class: doctrine | knowledge | memory | task | runtime | receipt truth.source: canonical URI + owner + revision truth.time: effective_at + observed_at + expires_at truth.quality: primary | derived + confidence basis truth.lifecycle: active | disputed | superseded + replacement
Try it yourself
Audit one important answer
Take an answer your system must get right and trace every fact needed to produce it.
- 1Label each fact as doctrine, knowledge, state, runtime, or receipt.
- 2Name its canonical source and owner.
- 3Record how quickly it can become stale.
- 4Define whether the worker must verify it live.
Reusable artifact
Truth record
Attach this metadata to facts that can change an outcome.
Claim: [the fact] Class: [doctrine / knowledge / state / runtime / receipt] Source: [canonical location] Owner: [person or system] Verified: [timestamp or version] Freshness rule: [when to recheck] Supersedes: [older record, if any]
Before you move on
Receipt checklist
- Consequential facts have canonical sources.
- Freshness rules match how quickly facts drift.
- Workers disclose uncertainty when they cannot verify.
- Old decisions can be traced without routing current work.
Primary sources
