# The Shared Knowledge System Software delivery depends on knowledge that is not fully visible in a requirement, a codebase, or an AI prompt. Product intent, organizational terminology, architecture constraints, domain meaning, operational assumptions, and prior decisions all affect whether an implementation is correct for a particular product. [Specification-First Delivery](/en-us/hub/specification-first-delivery) treats that knowledge as part of the delivery system itself. Its objective is to preserve the knowledge that qualified humans and AI can discover, apply, review, and maintain as the software evolves. ## 1. Knowledge System: Delivery Problem, Definition, and Scope A mature software team develops an informal memory system even when nobody designs one deliberately. Knowledge accumulates as the product evolves, and some of it may exist only in the minds of the people who have worked on it. For example: - An engineer may know that a field called `status` must be interpreted together with another field. - A Product Owner may know that a technically supported class of user is intentionally excluded from a particular workflow. - An architect may remember that an apparently simpler integration pattern was rejected because of failure isolation, cost, or another system-level constraint. These are ordinary examples of tacit knowledge: knowledge developed through work but not yet made explicit. Organizational knowledge creation begins with individuals, but it becomes reusable across the organization through processes that articulate and amplify what those individuals know.[^citation-01] When future work depends on that understanding, it needs to move from individual memory into durable sources that others can discover, review, and reuse. Human teams often compensate for missing explicit context through conversation. A new engineer sees something unusual and asks why it works that way. A reviewer recognizes an assumption that does not fit the domain. An experienced colleague notices that a locally reasonable change reopens a problem the team resolved years earlier. Developer work-habit research documented the cost of this recovery: developers spent substantial effort exploring code and interrupting teammates to reconstruct implicit knowledge, while much of what they recovered remained only in memory.[^citation-02] Coding agents change the speed and scale of the problem because implementation can now proceed before those informal corrections occur. A coding agent can produce a coherent implementation from an incomplete interpretation. If the missing knowledge concerns architecture, data semantics, regulation, product intent, or another product-specific constraint, the result may be internally consistent and still be wrong for the product. The risk increases when the first incorrect interpretation survives beyond the initial task. It can become part of a **chain of guesses**: a later specification, implementation decision, test, document, or AI session treats an earlier assumption as established knowledge. Subsequent participants then reason from a decision that nobody actually validated. Specification-First Delivery addresses this by preserving durable knowledge so future participants can work directly from established product understanding. > **Preserve durable product knowledge so another qualified participant can make a material change from established context.** In Specification-First Delivery, a **Knowledge System** is the shared, durable body of context, specifications, code, decisions, and evidence that humans and AI use to understand, change, verify, and continue software. It spans several forms of knowledge. Context explains the organization, product, domain, constraints, and operating environment. Specifications record intended behavior and agreed requirements. Code shows the current executable realization. Decisions explain material choices. Evidence records whether agreed conditions were satisfied. Knowledge gained during implementation and operation can update all of these. What makes this a **system** is the relationship between those sources of knowledge. They inform one another, establish where authoritative knowledge lives, and change together as the software evolves. A participant should be able to move from the current implementation to the intent and constraints that shaped it, and return newly established knowledge to the sources that future work will use. What makes it **shared** is that material knowledge is available to everyone in the team as well as their AI coding agents. Material knowledge is kept in durable, discoverable, reviewable sources that qualified humans and AI can use when relevant. Shared access alone does not remove differences in professional perspective. Communities of practice can develop different ways of knowing through their work, while organizational advantage depends partly on coordinating knowledge across those epistemic differences.[^citation-03] A Shared Knowledge System therefore needs to preserve professional ownership while making the material implications of product, domain, architecture, security, operations, and engineering knowledge available to a common delivery process. The resulting shared surface lets professional knowledge influence specifications, implementation, review, and future changes without collapsing distinct professional responsibilities. This paper focuses primarily on the context that allows a participant to understand the product and interpret a change correctly. [Requirements, Structured Discussion, and Increments](/en-us/hub/requirements-increments-and-structured-discussion) explains how a delivery need draws on that context to shape a coherent increment. [Knowledge Convergence Across the Increment Lifecycle](/en-us/hub/knowledge-convergence-across-the-increment-lifecycle) addresses how implementation learning returns to shared knowledge, while [Trusted Increments and Acceptance Evidence](/en-us/hub/trusted-increments-and-acceptance-evidence) defines the acceptance-time checks that confirm the resulting current-state knowledge is usable and coherent. ## 2. Codebase as Executable Knowledge The codebase is the most important source of knowledge in the Shared Knowledge System because it is the current executable realization of the product. It shows what the product does today, how its responsibilities are organized, which interfaces and dependencies are active, and how behavior is verified. It gives every qualified participant, including an AI coding agent, a dependable starting point for understanding the software they are changing. The codebase reveals current behavior, data dependencies, request paths, enforced constraints, and the tests that protect them. Supporting knowledge adds the original rationale and product interpretation that may sit outside the implementation itself. Together they give future participants a stronger basis for continuing the product responsibly. The supporting sources described in the sections below add the organizational environment, product intent, domain meaning, and standing requirements needed to interpret the executable implementation. AI coding agents need access to these sources alongside the codebase, whether they are kept in the codebase's `docs/` directory or retrieved through another appropriate mechanism. This allows an agent to consult the knowledge relevant to a change when it is needed. Long before AI-assisted delivery, software-design research had already separated the iterative reality of design from the rationalized account needed to review a design, guide coding, and support maintenance.[^citation-04] For AI-assisted delivery, that engineering account also needs to carry product intent, organizational constraints, specifications, decisions, code, and evidence so both humans and AI can work from established product knowledge. Throughout this technical white-paper series, product documentation is placed in the codebase's `docs/` directory. This tool-agnostic approach keeps it accessible to AI coding agents and to people working with the software. It is a practical convention for the series, and teams may expose shared knowledge through other mechanisms that provide the same accessibility and governance. With the current implementation as a foundation, the next layer is the organizational context in which the product operates. ## 3. Organizational Context A software product operates inside an organization that already has its own language, systems, architecture, policies, controls, and ways of working. This wider body of knowledge is **organizational context**. **Documented organizational context** is easier to cite or reference. It may include enterprise architecture standards, security policies, engineering practices, regulatory guidance, data classifications, approved technology platforms, organizational terminology, shared infrastructure, identity architecture, common service contracts, and the responsibilities of other systems across the organization. **Undocumented organizational context** is more difficult to preserve. Some of this knowledge becomes second nature to long-serving colleagues. A technology team and a business team working on the same product may use different terms to represent the same business concept. An engineer may already know which identity platform applications are expected to use. An architect may know which integration patterns the enterprise platform supports. A domain specialist may recognize an internal acronym immediately. A security professional may know which data classification triggers additional controls. Cross-functional work creates a harder problem because knowledge is often localized, embedded, and invested within the functions that produce it. An ethnographic study of new product development showed how participants may need to represent that knowledge, learn across functional knowledge boundaries, and sometimes transform what they know or do.[^citation-05] In software delivery, architecture, security, data, domain, platform, and engineering knowledge can remain rooted in specialized practice while the implications that affect the product are made usable across the team. In a large organization, much of this context should remain centrally maintained through architecture repositories, governed documentation platforms, internal portals, data catalogs, knowledge graphs, or services that AI can access through mechanisms such as MCP. We call this the **context layer**. Each authoritative source should remain with the organizational function responsible for maintaining it. The context layer allows specialist knowledge to stay under accountable ownership while making it discoverable to product teams and AI coding agents when a delivery decision depends on it. Compared with product context, organizational context is less specific to the product, but it remains essential in many cases. For example, a coding agent may need to discover how identity is handled across the enterprise, which infrastructure patterns are approved, what a particular internal service is responsible for, or which control applies to a category of data before it can interpret a product requirement correctly. The complete body of organizational knowledge is rarely relevant to one product, and even less of it is relevant to one implementation job. The product team therefore needs to make the organizational knowledge that materially shapes the product discoverable and record its product-specific implications explicitly. For example, an enterprise architecture standard may define several approved service-to-service authentication patterns. The product team should record which pattern this system uses, where that responsibility is implemented, and where the authoritative enterprise guidance can be found when a change requires deeper review. The enterprise standard remains at its authoritative source while the product records the knowledge needed to apply it correctly. The Knowledge System should therefore reference organizational knowledge while making its implications for the product explicit. ## 4. Product Context Organizational context explains how the wider enterprise works. **Product context** records how that wider knowledge applies to a particular product. Product context is the durable, product-specific interpretation of product intent, terminology, users, stable use cases, system responsibilities, dependencies, and external interfaces. It provides the minimum orientation another qualified participant needs before interpreting local requirements or implementation choices. Knowledge crossing functional or organizational contexts does not always require the same kind of work. At increasingly complex syntactic, semantic, and pragmatic knowledge boundaries, coordination moves from transfer to translation and then transformation.[^citation-06] Product context handles these cases at the level required by the product. Where common meaning already exists, it may only need to reference an authoritative source. Where meaning or practical consequences differ, the product records the interpretation or change needed for its own implementation and decisions. 1. **Organizational context** Shared enterprise knowledge such as architecture standards, policies, common platforms, organizational terminology, data classifications, and control requirements. It should normally remain centrally maintained and be retrieved when relevant. 2. **Product context** The durable interpretation of product intent, terminology, users, stable use cases, system responsibilities, dependencies, and interfaces that applies specifically to this product and should remain close to the software it governs. The exact documents and storage model can vary, but every product team should make several categories of context discoverable. 1. **Product intent** Explain why the product exists, which outcomes matter, what it optimizes for, and which apparent opportunities are intentionally outside its purpose. - Product purpose - Intended outcomes - Priorities and non-goals 2. **Personas** Identify the people or roles that interact with the product, what they are trying to accomplish, what they know, and what authority they hold. - User roles - Goals and responsibilities - Relevant permissions and assumptions 3. **Product glossary** Define how important terms are understood for this product, including cases where the product meaning differs from a wider organizational definition. - Domain terms - Product-specific terminology - Local meanings of organizational concepts 4. **Stable use cases** Capture recurring interactions that define how the personas use the product even when individual features and interfaces change. - Primary user goals - Recurring workflows - Important exception situations 5. **External interfaces and APIs** Identify the systems and providers on which the product depends, what responsibility each interface carries, and which contracts or provider obligations materially affect implementation. - Upstream and downstream systems - API and event responsibilities - Authentication and compatibility expectations ### 4.1. Product intent, personas, and stable use cases A backlog can describe many desired changes without explaining what the product is fundamentally trying to achieve. Product intent supplies that durable direction. It helps a participant distinguish a missing detail from a request that would pull the product away from its purpose, and it explains why two locally reasonable implementations may not be equally appropriate. Personas give that intent a point of view. The same function can mean something different for an administrator, an operations user, a customer, or an auditor because their goals, information, permissions, and authority differ. A useful persona records the distinctions that materially affect behavior and decisions. Stable use cases connect the two. Feature requirements may change frequently while the underlying user purpose changes slowly. A payroll administrator may still need to correct a payment before a processing deadline even after the interface, workflow engine, and validation rules have changed several times. Preserving that use case helps later changes remain connected to the product's enduring purpose rather than becoming a collection of unrelated tickets. ### 4.2. Product glossary Terminology is one of the easiest places for AI to make a plausible but incorrect interpretation. Consider an organization with a central human resources platform. An enterprise catalog may correctly describe it as the Human Resources System. Each dependent product also needs the product-specific meaning of that relationship. For a payroll application, the platform may be relevant primarily as the source of employee and compensation attributes needed to calculate pay. For a workforce demographics dashboard, it may instead be the source of organizational hierarchy and demographic attributes. Both products use the same upstream system, but its meaning to each product is different. A product glossary should state what a concept means for the product, which aspects matter, and which source is authoritative for the relevant facts. This gives an AI agent the product-specific meaning of a dependency before implementation begins. > **An organizational glossary defines a term globally. A product glossary defines what the term means to a product.** ### 4.3. External interfaces and APIs An API definition describes fields, types, and structural contracts. Product context adds the authority, compatibility, consistency, and provider obligations that shape how the product can use the interface. An upstream service may be authoritative for one attribute but not another. A downstream consumer may require backward compatibility even when a cleaner contract is available. An event stream may provide eventual rather than immediate consistency. A third-party provider may impose contractual or policy restrictions on how returned data or identifiers may be stored and retained. These obligations belong in product context because they affect how the product may interpret, persist, expose, and change information. Keeping them as durable product knowledge gives future interface changes an established basis for implementation and review. ## 5. Product-Wide Requirements and Constraints Some knowledge applies across many features because it expresses qualities, obligations, or structural constraints that the product is expected to preserve. Security, reliability, privacy, compatibility, and operational obligations are first-class delivery requirements. A system is correctly delivered only when its functional behavior and these standing obligations are satisfied together. A product team should therefore maintain standing requirements and constraints that are sufficiently stable to shape many changes. 1. **Security and privacy requirements** State material authentication, authorization, threat-control, audit, secret-handling, data-classification, retention, deletion, residency, and minimization expectations that apply across the product. 2. **Reliability objectives and requirements** Define expected service behavior under failure, recovery objectives, resilience expectations, observability needs, and other reliability obligations. 3. **Architecture requirements** Keep durable system responsibilities, approved technical direction, deployment model, dependency direction, and structural constraints as accessible product-wide knowledge. Architecture specifications then record the design and decisions for a specific architectural change. 4. **Compliance and external obligations** Identify legal, regulatory, contractual, provider, licensing, and policy requirements that materially affect how the product may process data or provide functionality. This is a distilled, product-specific interpretation of organizational context. 5. **Performance and capacity expectations** Make relevant latency, throughput, concurrency, volume, scaling, and resource assumptions visible before an implementation optimizes for the wrong operating profile. 6. **Operational requirements** State expectations for deployment, monitoring, supportability, rollback, environment management, diagnostics, and production ownership. 7. **Compatibility requirements** Record supported clients, interface versions, schema-evolution rules, legacy consumers, and behavior that must remain compatible unless an accountable change is approved. 8. **Accessibility and localization requirements** Where relevant, record durable accessibility, language, regional, formatting, and jurisdictional expectations that should apply consistently across features. Architecture provides a software-specific example of durable product knowledge. Architectural knowledge includes the design itself together with decisions, assumptions, context, and other factors that explain why a solution has its present form.[^citation-07] Keeping those factors discoverable gives later increments established system responsibilities and constraints to work from. In the Shared Knowledge System, architectural knowledge sits alongside product intent, domain semantics, interfaces, standing requirements, and the other knowledge that shapes delivery across many changes. The applicable categories vary by product. A small internal tool may need only a subset. A regulated, widely integrated, or high-consequence system may need much more depth. Specification-First Delivery applies the same proportionality principle here as it does to specifications: the required depth should reflect ambiguity, novelty, dependency, risk, and consequence. Standing product requirements remain authoritative across applicable features until an accountable decision changes them. A feature-specific requirement, by contrast, is established for the scope of that feature or increment. For example, "deploy this service as a container on the approved platform" may be a product-wide architecture requirement. Later feature specifications can reference that standing requirement. If all customer identifiers are subject to a defined retention rule, that requirement should remain discoverable as product knowledge for every relevant change. Stable requirements can be maintained once, reviewed when they change, and referenced by later specifications and implementation work. This reduces repetition without weakening control. ## 6. Product-Specific Domain Knowledge Product-specific domain knowledge captures how the product represents and operates on its domain. It covers meanings and rules that shape implementation across many local changes. This is where technically correct code can be especially misleading. A formula can compile while using the wrong business methodology. A database field can have the correct type while representing the wrong meaning. A state transition can be valid in code while being impossible in the business process. A query can return the latest record when the requirement actually depends on the record that was effective at a historical point in time. The product team should preserve domain knowledge that materially changes how data and behavior must be interpreted. 1. **Calculation methodologies** Define formulas, ordering rules, rounding, aggregation, exclusions, adjustment logic, and other methods whose correctness depends on domain interpretation rather than syntax. 2. **Data semantics** Explain what material data represents, which values are valid, how fields relate, how data changes over time, and which interpretations are incorrect even if the schema permits them. 3. **Business invariants** Record conditions that must remain true across features, such as uniqueness, reconciliation, eligibility, conservation, or consistency rules. 4. **State and lifecycle semantics** Define meaningful states, allowed transitions, terminal conditions, reversibility, and lifecycle rules explicitly enough for implementation and review. 5. **Sources of truth** State which source is authoritative for a defined fact, what local copies represent, how disagreement is handled, and when freshness changes the interpretation. 6. **Temporal semantics** Distinguish concepts such as event time, processing time, effective date, booking date, historical state, and current state when those differences affect behavior. 7. **Reference data and classifications** Record the meaning and ownership of controlled codes, hierarchies, taxonomies, classifications, and other reference values used to interpret domain data. 8. **Known domain exceptions** Preserve stable exceptions and special cases as explicit domain knowledge so future implementation continues to honor them. ### 6.1. Calculation and data semantics A calculation implemented in source code tells a reader what the current system does. The Shared Knowledge System should also explain why that methodology is correct for the product. Rounding may occur at an intermediate step rather than at the end. Values may be excluded under certain business conditions. A ratio may use a regulatory denominator rather than the mathematically obvious one. A historical period may need to be restated after a correction. The Shared Knowledge System should record these rules explicitly alongside the implementation and tests that apply them. Data requires the same explicit treatment. A semantic schema defines what each material field means in the Shared Knowledge System. For a `timestamp`, the semantic definition should tell the agent whether it represents event time, the time the organization learned about the event, effective time, or storage time. For `department`, it should identify whether the value represents the employee's current hierarchy, the hierarchy effective on a reporting date, or a locally maintained reporting category. For `country`, it should define the accepted representation, such as `United States`, `US`, or `USA`. These semantics should be clearly defined in the Shared Knowledge System alongside the schema and implementation that use them. ### 6.2. Sources of truth and time Products frequently rely on several authoritative sources at once. One system may be authoritative for customer identity, another for contractual status, and another for the current operational state of a workflow. Even within one object, different attributes may have different authoritative sources. A source-of-truth statement should identify the exact fact for which a source is authoritative. The product team should also record what a local projection or cache represents and how disagreements between sources are resolved. Temporal meaning also needs to be explicit. "Current," "latest," "effective," and "recorded" may refer to different points in time. AI is capable of completing a technically conventional interpretation when the product actually requires a domain-specific one. The Knowledge System should make the intended meaning discoverable before implementation depends on it. ## 7. Progressive Context Loading A Shared Knowledge System needs selective context loading so the working context remains concentrated on knowledge that is relevant to the current task. Modern coding tools can retrieve large repositories, search external knowledge systems, load instruction files, activate skills, call MCP tools, inspect issue trackers, and read architecture documentation. These capabilities increase access to knowledge. Progressive Context Loading determines which of those sources should enter the working context as the task becomes more specific, reducing **context bloat** from irrelevant information. > **Progressive Context Loading is the practice of making context more specific as the work becomes more specific, while retrieving broader organizational knowledge only when it is relevant to the current decision.** The objective is to maintain a context window with a high proportion of relevant, authoritative knowledge, recognizing that attention is a scarce resource. Distributed teams expose a related access problem. Across thirteen geographically dispersed teams, recurring mutual-knowledge failures included failure to retain contextual information, uneven distribution of information, difficulty recognizing its salience, and differences in access speed.[^citation-08] Relevant context therefore needs to remain discoverable and recognizable when work depends on it. Progressive Context Loading addresses the separate selection problem for AI-assisted delivery: which authoritative source should enter the working context as a decision becomes more specific. The relevance path moves from organization-wide knowledge to product, repository or module, and finally the current job. **Context loading: Increase specificity as work narrows** 1. **Organization** Keep enterprise architecture, policies, common platforms, organizational terminology, and other product-agnostic knowledge centrally available for retrieval when a product team needs it. 2. **Product** Maintain durable product intent, personas, terminology, stable use cases, interfaces, product-wide requirements, and domain knowledge close to the software they govern. 3. **Repository or module** Load the architecture, responsibilities, dependencies, conventions, and local documentation that apply to the area currently being inspected or changed. 4. **Current job** Add the specific requirement, execution scope, constraints, acceptance criteria, and current questions needed to perform the immediate work. This model changes the question from "What can the agent access?" to "What should the agent know now, and where should it look next if the work crosses into another area?" ### 7.1. Governing Instructions as a Knowledge Directory **Governing Instructions** are mandatory repository instructions that coding agents should read for every task. Depending on the coding harness, they may appear in `AGENTS.md`, `CLAUDE.md`, or `copilot-instructions.md`. They should establish stable rules, navigation, and required behavior in a concise form that routes the agent to deeper product knowledge when needed. A coding agent may need to know on every job that it must update the relevant product documentation when behavior changes, use a particular validation approach, respect protected areas, or consult a specific architecture source before changing a shared interface. These are suitable candidates for governing instructions because they influence how the agent operates across work. Detailed product history, API contracts, domain formulas, and operational runbooks remain discoverable and are loaded when the current task requires them. ### 7.2. Locate knowledge according to scope Context becomes easier to select when its location reflects where it applies. Repository-level knowledge belongs at the repository level. Module-specific architecture should be discoverable from that module. A folder that contains a coherent responsibility can use a local `README.md` file to explain what belongs there, what depends on it, and which deeper documents matter before changes are made. The same principle applies outside the repository. Enterprise architecture, security policy, or platform documentation can remain in centrally governed sources when they apply across many products. The product team needs enough local knowledge to identify when those sources become relevant. ### 7.3. Use documents as navigation as well as storage A useful document should either provide an answer or direct the reader to the authoritative source. In this context, the reader may be an AI coding agent. Take a module README as an example. It can state that the module consumes identity data from a shared platform, link to the product-level interface description, and identify the organizational security standard that must be consulted before authentication behavior changes. This creates a chain of relevance. The participant starts with local knowledge and expands outward only when the current work requires broader context. ### 7.4. Retrieve broader knowledge when the work requires it External knowledge access is particularly useful for product-agnostic material. An organization can keep architecture standards, policies, platform documentation, or controlled terminology in centrally governed sources and expose them through internal search or an MCP-accessible service for on-demand retrieval. The product team should identify when such retrieval is necessary. Changing the product's authentication model may require consulting the current enterprise identity standard. A local UI label can usually be handled from product-level context. Skills and named agents provide specialized context for particular classes of work where the coding tool supports them. 1. **Skills** Skills are discrete, action-oriented abilities available to an AI model. Like tools in a toolbox, they can be selected by an AI coding agent when relevant. 2. **Named Agents** A Named Agent is a specialized instance of an AI model assigned a specific persona, role, system prompt, and set of skills for a targeted task in the software development lifecycle. A human user explicitly directs the AI coding tool to use that agent. Where a coding tool loads skills selectively, the AI coding agent may load a skill at its discretion when it identifies a matching class of work. Skills are therefore appropriate for task-specific procedures. Mandatory repository behavior belongs in governing instructions that apply on every relevant task. A named agent can encode useful specialization, while explicit agent selection remains part of the workflow. Governing instructions provide the mandatory behavior regardless of which specialist is selected. Progressive Context Loading keeps these mechanisms complementary. Governing instructions establish mandatory behavior and navigation. Product-level and module-level documents hold durable knowledge. Skills provide specialized procedures where the tool supports them. External services provide broader organizational knowledge when required. The current job contributes the information specific to the present change. ## 8. Knowledge Maintenance and Synchronization A Knowledge System becomes dangerous when it is authoritative enough to influence work but stale enough to describe a system that no longer exists. Documentation practice also shows why durable knowledge cannot be treated as self-maintaining. In empirical work on software documentation, engineers updated documentation less promptly and completely than processes and managers often prescribed, even though outdated documentation could remain useful in some circumstances.[^citation-09] When documentation is used as current product knowledge, that maintenance gap becomes a delivery concern. AI-assisted implementation raises the consequence of stale material because an outdated source can influence generated code before an experienced colleague notices the discrepancy. Knowledge maintenance therefore belongs inside software delivery. When implementation changes a module's responsibility, architecture, interface, behavior, or durable assumptions, the corresponding knowledge should change in the same delivery increment. This keeps the implementation and the knowledge used by the next participant synchronized. ### 8.1. README files as local current-state knowledge A `README.md` can be one of the most useful forms of product context because it is naturally discoverable from the code it describes. A meaningful folder README should answer questions such as: - What responsibility does this area own? - What belongs here, and what does not? - Which other parts of the system depend on it? - Which assumptions or constraints matter before it is changed? - Which deeper architecture, domain, or interface documents should be consulted? The README should describe the current state. If implementation changes the answers to those questions, updating the README is part of the implementation. This requirement is suitable for governing instructions because it is mandatory repository behavior. Governing instructions apply the requirement consistently across relevant work. ### 8.2. Durable internal product documentation A repository also needs knowledge that is too broad or detailed for a local README. Architecture descriptions, domain semantics, interface contracts, product-wide requirements, and other durable material can live under `docs/` or an equivalent governed documentation surface. An illustrative repository structure might be: ```text README.md docs/ architecture/ domain/ interfaces/ product/ src/ feature-a/ README.md feature-b/ README.md ``` A product team may use another repository structure or keep some authoritative knowledge outside the repository. Specification-First Delivery requires the chosen structure to keep current knowledge versioned where appropriate, reviewable, discoverable, and connected to the implementation it describes. > **Specification-First Delivery requires each product team to use a directory structure that describes the product clearly; the structure can vary by product.** ### 8.3. Public product documentation as a delivery output Some product knowledge is intended for users, customers, operators, integrators, or other external readers. A product team can maintain a documentation surface whose content is suitable for publication as the product evolves. User behavior, integration guidance, supported workflows, operational instructions, or public API information can then be updated as part of the same work that changes the product. This keeps public documentation synchronized with the software and with the knowledge used during delivery. > **Public product documentation should evolve with the product and be included in the same delivery path.** **Synchronize implementation and product knowledge** A delivery increment should update the knowledge surfaces that describe the behavior or responsibility being changed. 1. **Change implementation** Modify the agreed behavior, architecture, interface, or system responsibility. 2. **Update local knowledge** Revise the relevant folder README or nearby module documentation when current responsibilities or assumptions have changed. 3. **Update durable product knowledge** Revise the architecture, domain, interface, or other internal product documentation affected by the change. 4. **Publish relevant documentation** Include user-facing or integration documentation in the release path when the delivered behavior changes what external readers need to know. Documentation updates should remain proportional to the change. A local refactor that changes no responsibility or behavior may require no documentation update. A change that alters a public interface, domain meaning, system responsibility, or operating model probably does. > **Preserving knowledge strengthens the use of expertise** > > Professional judgment remains essential after established knowledge has been externalized. Preserving earlier decisions lets qualified professionals spend their judgment on the next unresolved problem instead of repeatedly reconstructing decisions the organization has already made. ## 9. Current-State Knowledge and Delivery Records The Knowledge System contains two complementary forms of record. A product team needs **current-state knowledge** that answers, "What is true about the system now?" It also needs **delivery records** that answer, "What work was requested, what happened, and how did the system reach this state?" A new coding job should use the relevant specification and current context to understand the existing architecture. The organization should also retain job specifications, status reports, material deviations, decisions, and evidence that explain how important changes were delivered. When sources conflict, these historical records provide valuable evidence for resolving the discrepancy. 1. **Current-state knowledge** Describes the system as it exists now, including product intent, terminology, architecture, interfaces, domain semantics, requirements, and local README guidance. It should remain usable as direct context for future work. 2. **Delivery records** Describes how the system changed, including feature jobs, bug-fix jobs, status reports, material deviations, implementation findings, decisions, and evidence that preserve delivery history and traceability. Separating current-state knowledge from delivery records is particularly useful for feature and bug-fix work. A feature job specification describes a change to be made. A bug-fix job records a defect, the intended correction, relevant constraints, and how the correction will be verified. Status reports record what happened during execution. These artifacts belong in the wider Knowledge System because they preserve delivery history and support traceability. The resulting system state should also be reflected in current-state knowledge. If a feature changes an API responsibility, the current interface documentation should be updated. If a bug fix reveals that a domain invariant had never been documented, the domain knowledge should be updated. If implementation changes how a module works, the relevant README should describe the resulting state. > **The delivery record explains the change. Current-state knowledge explains the result.** The detailed structure and lifecycle of specifications, job execution, decision history, and acceptance evidence belong to later parts of the framework. Their relationship to this paper is simpler: as delivery proceeds, they join the same Shared Knowledge System and should remain connected to the current product knowledge that gives them meaning. The practical objective is to ensure that a qualified human or AI participant can discover what the product is trying to achieve, what its terms mean, which requirements and constraints apply, what important domain concepts mean, where authoritative knowledge lives, and what must be updated when the software changes. That is how the organization avoids rebuilding its own understanding every time people, teams, vendors, models, or tools change. [^citation-01]: Nonaka, I. (1994). *A Dynamic Theory of Organizational Knowledge Creation*. Organization Science, 5(1), 14–37. [DOI](https://doi.org/10.1287/orsc.5.1.14). [^citation-02]: LaToza, T. D., Venolia, G., & DeLine, R. (2006). *Maintaining Mental Models: A Study of Developer Work Habits*. Proceedings of the 28th International Conference on Software Engineering, 492–501. [DOI](https://doi.org/10.1145/1134285.1134355). [^citation-03]: Brown, J. S., & Duguid, P. (2001). *Knowledge and Organization: A Social-Practice Perspective*. Organization Science, 12(2), 198–213. [DOI](https://doi.org/10.1287/orsc.12.2.198.10116). [^citation-04]: Parnas, D. L., & Clements, P. C. (1986). *A Rational Design Process: How and Why to Fake It*. IEEE Transactions on Software Engineering, SE-12(2), 251–257. [DOI](https://doi.org/10.1109/TSE.1986.6312940). [^citation-05]: Carlile, P. R. (2002). *A Pragmatic View of Knowledge and Boundaries: Boundary Objects in New Product Development*. Organization Science, 13(4), 442–455. [DOI](https://doi.org/10.1287/orsc.13.4.442.2953). [^citation-06]: Carlile, P. R. (2004). *Transferring, Translating, and Transforming: An Integrative Framework for Managing Knowledge Across Boundaries*. Organization Science, 15(5), 555–568. [DOI](https://doi.org/10.1287/orsc.1040.0094). [^citation-07]: Kruchten, P., Lago, P., & van Vliet, H. (2006). *Building Up and Reasoning About Architectural Knowledge*. In *Quality of Software Architectures*, Lecture Notes in Computer Science 4214, 43–58. [DOI](https://doi.org/10.1007/11921998_8). [^citation-08]: Cramton, C. D. (2001). *The Mutual Knowledge Problem and Its Consequences for Dispersed Collaboration*. Organization Science, 12(3), 346–371. [DOI](https://doi.org/10.1287/orsc.12.3.346.10098). [^citation-09]: Lethbridge, T. C., Singer, J., & Forward, A. (2003). *How Software Engineers Use Documentation: The State of the Practice*. IEEE Software, 20(6), 35–39. [DOI](https://doi.org/10.1109/MS.2003.1241364).