--- name: context-design description: Design and improve the information an AI workflow uses to reason, investigate, and act. Use for enterprise knowledge and document interpretation, retrieval, long-context work, task memory, changing business state, or failures caused by missing, misleading, inaccessible, or poorly organized context. --- # Context design Give the intelligence the material it needs to make the next useful decision, in a form that preserves business meaning. Work backward from the proposed behavior rather than beginning with an index, vector database, prompt length, or memory feature. Good context can enable an investigation the organization could not previously afford; poor context can make a powerful model confidently solve the wrong case. Inspect what the workflow currently receives and what an expert uses to reach a sound result. The gap may be an absent source, a wrong entity, missing temporal context, a lost table relationship, inaccessible evidence, an unexpressed decision rule, or a capability the current product already provides. Improve the relevant boundary and test whether the task becomes more useful. ## Reconstruct the expert's information advantage Choose a representative decision, preferably one where an expert changed the initial answer. Follow the evidence they considered, rejected, or requested and the distinction that changed the outcome. Learn whether they were applying an explicit rule, interpreting ambiguous language, recognizing a causal sequence, comparing precedents, or navigating the organization to obtain missing knowledge. Avoid treating the final document as the complete knowledge requirement. A credit recommendation may depend on the effective covenant amendment, the measurement period, the reporting entity, an approved adjustment, and a subsequent event. A service decision may depend on an installed modification that is absent from the product-family manual. The missing relationship can matter more than another thousand pages of documents. Separate what is needed to understand the situation from what is needed to authorize or execute a decision. Background can be compacted or reused. Current eligibility, balance, compatibility, or approval may need a fresh authoritative check. A model should not mistake a persuasive historical example for present authority. Look for valuable questions the existing workflow omits. Richer context may allow the system to compare alternative explanations, anticipate a downstream dependency, or ask one discriminating question before an expensive commitment. Design for those behaviors rather than limiting the context to whatever columns an existing report happened to contain. ## Preserve the relationships that carry meaning Build a task-specific view of the relevant business objects and their relationships. Resolve aliases and versions before combining sources. The same company name can refer to several legal entities; the same asset label can refer to successive machines; the same contract can have different terms across periods. Identity resolution should expose ambiguity that matters to the decision instead of silently choosing a convenient match. Documents carry structure. A number may depend on its row, column, unit, reporting period, footnote, or definition. A contract clause may be displaced by an amendment or limited by a neighboring exception. A diagram may establish a dependency that disappears in plain OCR text. Preserve or retrieve enough of that surrounding structure to interpret the item correctly. Use the representation that serves the reasoning. Structured tables and calculations can supply precise quantitative facts; native document views can preserve layout and clause relationships; visual interpretation can resolve diagrams; relational queries can establish membership or history. Discover which of these the present host and source product can perform well before building transformations of your own. Keep observation, interpretation, and authority distinguishable. A customer's description of a seized machine is a report; a signed inspection is an observation; an engineer's diagnosis is a conclusion. A new report can challenge a conclusion without automatically replacing it. Give the model the disagreement and the basis for resolving it when that disagreement affects action. Time and applicability belong with consequential evidence. Decide what was knowable at the decision time, what is true now, and which version governs the requested task. A retrospective evaluation must not leak the eventual outcome into the candidate's inputs. A current planning task should not continue applying yesterday's expired offer because its text remains in conversation history. ## Discover the simplest capable information path Inspect the tools, source-application features, content representations, model interfaces, and host surfaces available for this task. Current capabilities may let the system use complete applicable documents, reason over visual material, query business state directly, follow linked records, or maintain a task across new events. Explore promising affordances on the workload rather than assuming a permanent retrieval architecture. Start by giving a capable candidate enough applicable material to solve a few consequential cases. This establishes whether the underlying reasoning is possible and what evidence is decisive. Then compare practical ways of supplying that material under the workload's access, freshness, latency, volume, and cost constraints. A successful complete-context experiment does not settle the production design, but it prevents spending months optimizing retrieval for a task the candidate cannot reason through. Use retrieval when selection adds value, and evaluate selection by the decision it enables. Semantic resemblance alone is often insufficient. A high-scoring precedent for the wrong entity, jurisdiction, equipment revision, or effective period can be actively misleading. Apply the relevant applicability and permission constraints, then let the model investigate within the remaining material. A larger context window can remove brittle fragmentation when the relevant source set is bounded and the model uses it well. It can also add distraction, cost, and latency. A graph can express stable relationships needed for repeated reasoning; it can also introduce expensive curation with no demonstrated benefit. A domain summary can speed ordinary work while losing the exception that controls a rare case. Compare these tradeoffs on the actual decision, not on a preferred architecture diagram. Let investigations acquire context progressively when the path depends on what is found. Give the model useful search and inspection operations, enough metadata to choose among them, and a way to recognize that a material question remains unanswered. Stop gathering when additional information is unlikely to change the next action at the required confidence or would arrive after its useful window. An exhaustive dossier can be a worse product than a supported decision made in time. Do not hide inaccessible evidence behind a confident summary. Distinguish an absent record, a failed retrieval, and a permission denial because they imply different next actions. Ask an authorized person for the narrow missing fact or route the work to the proper scope when that resolves the task. Do not infer a negative finding from inability to inspect the source. ## Make context change safely with the work Separate the material used in a model call from durable business state and reusable organizational knowledge. The current task may need a working hypothesis and unresolved questions. The enterprise system owns commitments and outcomes. Reusable knowledge needs an owner and a correction mechanism. One large conversation history should not serve all three purposes. Retain knowledge because it improves future decisions, not merely because it was generated. An accepted product exception may apply only to one serial or customer. A workaround may expire with a software release. An operator correction may reveal a useful rule or simply a preference for that case. Preserve scope and applicability before promoting the observation into reusable guidance. When material facts change, revise the conclusions that depended on them. A changed delivery date can invalidate a plan without invalidating the diagnosis. A new covenant amendment can change the compliance test without changing the financial statements. Track enough dependency to refresh affected reasoning deliberately; repeatedly rereading every source may be unnecessary, while leaving a derived summary untouched can preserve an obsolete decision. Compression should preserve the distinctions that control behavior: who asserted a fact, its applicable entity and period, unresolved alternatives, obligations and exceptions, and the current external commitment state. Test compression on cases where a small omission changes the action. Removing “unless,” changing a unit, or merging proposed and approved terms can be more consequential than losing several paragraphs of background. Permissions travel with derived context. A summary, embedding, cached answer, or evaluation example can reveal the source even when it omits a document link. Design shared context according to the permitted audience and purpose, and recheck access when a long-running task or its participants change. Retrieved documents and messages remain evidence, not instructions that can redefine the user's task or tool authority. ## Diagnose context failures with contrasts Use comparisons that isolate why the workflow fails. Hold the task and candidate constant, then compare its behavior with the available production context, a carefully assembled applicable packet, and a minimal packet containing the decisive evidence. If the model succeeds only with the assembled packet, inspect selection, structure, or missing relationships. If it fails even with the decisive evidence, investigate interpretation, instructions, or model capability before expanding the index. Test the converse as well. Remove the decisive fact, replace it with a stale version, or introduce a highly similar but inapplicable source. The system should change its conclusion or seek the missing evidence when appropriate. A model that gives the same confident answer regardless of these changes may be relying on a pattern rather than the supplied context. Judge evidence use at the level of the consequential claim. A correct citation to purchase age does not support warranty coverage; a correct link to an inventory count does not establish part compatibility; a financial statement total does not prove compliance with an amended covenant definition. Evaluate the relationship between evidence and conclusion, not only whether a cited document exists. For adaptive investigations, evaluate the information request itself. Did the system ask for an observation that separates the plausible explanations, or merely request more data? Did it recognize a fact already available in another authorized source? Did the cost and delay of obtaining the fact make sense relative to the decision it could change? These questions reveal whether context design is enabling expert work. ## Worked tradeoff: a covenant calculation that uses the right obligation A borrower submits financial statements and a compliance certificate. A generic document search retrieves the original agreement's leverage definition and calculates a ratio correctly. An effective amendment permits a specific adjustment for one period, while another entity in the same group has a different covenant. The arithmetic can pass every numerical check and still answer the wrong legal-entity and period question. The useful context design resolves the borrowing entity and facility, identifies the applicable agreement and amendments as of the measurement date, preserves the definition and conditions around the adjustment, and joins those terms to the relevant financial period. Deterministic calculation handles the approved inputs. The intelligence identifies an ambiguous adjustment, explains its effect, and seeks the narrow interpretation from the accountable credit or legal reviewer. This does not require building a universal contract knowledge graph before the first case. A supported linked-document view and a bounded applicable packet may be enough. Expand the maintained structure when repeated queries, changing terms, or portfolio coverage justify it. The deliverable should make the next decision better and leave a credible path to repeated operation, using the simplest present capabilities that do the work. For source fragments, an applicable packet and controlled contrasts, read [the worked evidence example](references/applicable-evidence.md). Use it when entity, time or a missing condition could change the conclusion; its fictional documents illustrate the method rather than supplying policy for another task.