> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/platform-overview/design-principles.md). # Design Principles The engineering trade-offs behind source-aware data, bounded workflows, explicit action confirmation, and measured improvement. Concurrence's architecture is organized around the conditions a workflow needs to succeed: usable evidence, an allowed action, an observable result, and a way to improve the next attempt. The principles below connect those needs to the platform's design choices and their limits. ## 1. Preserve Evidence and Make Reads Useful Healthcare records differ in freshness, completeness, and authority. A patient report and an external record can disagree without either becoming disposable. The world model retains supported observations with their source and derives current read views using explicit projection rules. This separates recording evidence from selecting a value for use. Consumers can use a projection instead of resolving the whole history during each interaction, while retained provenance helps an investigator understand the result. [Memory](/agent/memory.md) applies the same principle to understanding that develops across interactions: observe useful information, consolidate a bounded model, and recall detail when the task needs it. Preserve the difference between what a person reported, what a source system recorded, and what a model inferred. Repeatedly summarizing an interpretation does not create independent supporting evidence. The trade-off is that derived state has a freshness boundary. A write can be accepted before it appears in a projection, and a generated summary can omit detail. Workflows need explicit retrieval when a decision depends on facts that may have changed. See [World Model](/data/world-model.md). ## 2. Compose Workflows Around Information Requirements A Context Graph organizes work into objectives, transitions, and eligible operations. It lets an author specify what evidence is needed before moving on without scripting every sentence of the conversation. An agent supplies the broader identity and guidance; the service and runtime supply the operating configuration. For scheduling, the meaningful transition is having enough verified information to request the permitted change. Counting questions asked is a weak substitute. Existing context can shorten the path, while conflicting information can require another lookup or a person. Choose the degree of control for each part of the problem. Interpreting a request and explaining options benefit from model judgment. Checking a permission, validating an identifier, or enforcing an enabled approval gate belongs to the operation's control boundary. Declarative definitions make those choices reviewable; the [Reasoning Engine](/agent/reasoning-engine.md#what-the-designer-controls) explains how they fit together. Composition makes parts reusable and changes reviewable. It also means behavior depends on several parts at once. Reusing a graph on another channel or with different tools requires validation in that setting. Model-driven navigation remains probabilistic, even when the authored graph is explicit. See [Core Concepts](/platform-overview/core-concepts.md) and [Context Graphs](/agent/context-graphs.md). ## 3. Put Controls at the Boundary They Govern An instruction describes intended behavior. Authorization determines who can perform an operation. Validation checks whether an operation is permitted with the supplied input. An observer records evidence. A human decision supplies the judgment assigned to that person. Those controls can work together, but they establish different things. A prompt cannot grant an integration permission, and an observed guardrail verdict does not necessarily block a response. The [Runtime Safety](/operations-and-safety/runtime-safety.md) control map identifies the current enforcement and observation boundaries. External actions also need their own confirmation. Recording a requested appointment change establishes intent; the scheduling system's acknowledgement establishes the outcome its contract supports. Keeping these distinct makes failed and ambiguous work visible for reconciliation. The cost is additional integration and operating work: define the result, handle ambiguity, and staff the fallback. That work is part of making a deployment reliable, not something a more confident agent response can replace. ## 4. Improve Through Comparable Evidence and Deliberate Releases An interaction can reveal a missing source, an ineffective tool, an unclear workflow, or a behavior that needs changing. Retained runs, tests, and analytical evidence make those findings available to the team responsible for the next version. This separates two loops. Execution uses the current definitions and available knowledge to handle today's work. Improvement evaluates that evidence and proposes better definitions or reusable views for later work. Selecting behavior in the background during one interaction belongs to execution; it is not by itself evidence of learning across interactions. See the [memory design direction](/agent/memory.md#execution-and-longer-term-improvement). Separate the question from the configuration being tested. Define the outcome and baseline, identify the required evidence, then compare a candidate on representative cases. Keep missing artifacts and changed populations visible; a better average score can conceal a regression in a consequential segment. Simulation reduces the cost of exercising behavior before deployment. It does not reproduce every channel or external side effect, so audio, integration, and operational tests supply additional evidence. The team decides whether that evidence is sufficient to release. The resulting improvement is an engineering process. A metric trend does not automatically rewrite a graph or promote a version. Preserve useful cases and reviewed configuration so later work builds on what was learned. See [Testing and Evaluation](/testing/testing.md), [Continuous Improvement](/agent/pattern-discovery-and-reuse.md), and [Deployment Model](/platform-overview/deployment-model.md). ## Apply the Principles to a Deployment Use [How It Works](/platform-overview/how-it-works.md) to trace the boundaries through a concrete interaction. Use [Operating Model](/platform-overview/operating-model.md) to assign the decisions behind them, and [Evaluating Concurrence](/platform-overview/evaluating-amigo.md) to identify the evidence a technical review should examine. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.concurrence.com/platform-overview/design-principles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.