Knowledge System Readiness for Specification-First Delivery

The Shared Knowledge System defines the connected organizational knowledge used to discuss, specify, implement, verify, accept, and continue software delivery. For an existing product, the next question is operational: what must a team establish before a qualified person or AI system can rely on that Knowledge System to perform responsible delivery work?

This paper defines that readiness baseline and a practical method for establishing it. Later papers examine Product Intent, Personas and Actors, Stable Use Cases, Product Language and Data Semantics, Product Architecture, standing requirements, specialist requirements, and Governing Instructions in greater depth.

The objective is to ensure that knowledge material to a decision is authoritative, reachable, connected to the current implementation, and routed to the correct professional authority when it is incomplete or disputed.

Back to top

1. Knowledge System Readiness: Definition and Acceptance Condition

Knowledge System readiness is the condition in which a qualified participant can obtain the product knowledge, implementation evidence, applicable constraints, and decision paths required for the responsibility they are about to perform.

Readiness is therefore a property of the delivery system around a product. Product knowledge may be stored in a source repository, governed document platform, architecture repository, service catalogue, control system, knowledge graph, or another maintained source. The relevant question is whether the participant can identify which source is authoritative for the subject, reach it through the normal access path available to that participant, and determine who has authority when the available knowledge is insufficient.

A practical acceptance condition is the unfamiliar-participant test:

A Knowledge System is ready for a defined responsibility when a qualified participant with no prior history of the product can orient to the product, discover and apply the authoritative knowledge and constraints relevant to that responsibility, connect them to the current implementation, and route unresolved material questions to the correct decision owner.

The participant may be an engineer joining the team, a Product Owner covering an unfamiliar area, an architect reviewing a dependency, a specialist applying a standing requirement, or an AI coding agent beginning an authorized task. The test is role-specific because each participant needs different knowledge and has different authority.

In a grounded theory study of 18 newcomers across 18 software projects, Dagenais et al. identified orientation aids and obstacles and theorized that early experimentation, internalizing project structures and cultures, and progress validation shape newcomer integration.¹ The unfamiliar-participant test narrows that broader integration problem to a defined delivery responsibility: whether a qualified participant can orient to the product, retrieve and apply the necessary knowledge, and escalate what remains unresolved.

For a practical baseline, the Knowledge System should make the following questions answerable:

• Why does the product exist, who uses it, and which stable outcomes or use cases should survive local implementation changes?

• How is the current system organized, which components or teams own which responsibilities, and which dependencies and interfaces matter to the work?

• Which standing product, security, privacy, reliability, operational, data, accessibility, compatibility, localization, or other requirements apply?

• Where is the current implementation, and how can a qualified engineer inspect, configure, build, run, or otherwise meaningfully verify the relevant baseline?

• Which Governing Instructions apply to human and AI contributors performing delivery work?

• Which source is authoritative for each material subject, and how does a participant reach it through the access route available to that participant?

• Who has decision authority when knowledge is absent, contradictory, inaccessible, or no longer accurate?

Proportionality determines how this baseline is applied. For each responsibility, the team determines which knowledge, implementation evidence, access routes, constraints, and decisions are necessary for the proposed work. For example, a missing accessibility requirement may be immaterial to a backend refactor but blocking for a user-interface change.

Identified gaps are valuable knowledge and should be recorded. A team can resolve them before dependent work requires an answer, or record a clear condition for when they must be resolved.

Back to top

2. The Delivery Baseline: Intended Knowledge, Implementation Evidence, and Authority

A usable delivery baseline connects three perspectives that software teams often hold separately: intended knowledge, implementation evidence, and decision authority.

Code is essential evidence of the current implementation, but it does not by itself establish which behavior is intentional. A workaround may remain after a production break-fix, a specialized calculation may serve one user request without applying to every case, or a test may preserve an accidental interpretation. Conversely, a document that describes intended behavior may not reflect how the current system actually behaves or whether the documented setup still works.

The Knowledge System becomes useful for delivery when these perspectives are connected. A participant can inspect implementation evidence, locate the corresponding intent or constraint, and identify the authority that resolves a discrepancy.

When recorded intent and observed implementation differ, the team should establish the authoritative interpretation through the relevant decision owner:

1. record the discrepancy as a readiness gap;

2. identify which role has decision authority for the disputed subject;

3. establish whether the implementation is wrong, the recorded knowledge is outdated, or a new decision is required;

4. update the authoritative current-state knowledge when the decision is resolved; and

5. route any required product-state change through an appropriate delivery increment.

Capability Continuity depends on keeping recorded intent and implementation evidence aligned under clear authority. When the organization has already made a relevant decision, a future participant should be able to retrieve that decision directly. When implementation has materially diverged from documentation, the discrepancy should be visible and routed for resolution before the document guides further work.

Back to top

3. Establishing the Readiness Baseline

Preparing a Knowledge System is an evidence-producing delivery activity. Before delivery depends on it, the team needs an initial baseline that makes the relevant product scope, readiness accountability, authoritative knowledge, access and escalation routes, engineering baseline, and known gaps clear.

The activities below are framework guidance for discussing what this baseline needs. A team does not need to complete every activity at maximum depth before work begins. Instead, it can identify the knowledge needed for the next responsibility, invite the appropriate decision owners to contribute it, and record gaps with an owner and a required-before condition.

These activities establish an initial baseline. The later validation and gap-management activities test that baseline with unfamiliar participants, often AI coding agents operating within authorized scope, whenever a new responsibility or increment depends on it. Each failure to orient, retrieve, interpret, verify, or escalate exposes a readiness gap and a practical improvement point. The accountable decision owner can improve the Knowledge System directly or, more commonly, ship the improvement with the delivery increment that depends on it. This keeps the initial baseline proportionate while making the next responsibility more reliably supportable.

Back to top

3.1. Define the preparation scope and accountability

Start by defining what is being prepared. For a small product this may be one repository and one service. For a larger platform it may include several repositories, services, external interfaces, document systems, and organizational control sources.

The preparation scope can identify:

• the product or system being prepared;

• the implementation repositories, services, or components included;

• the participant roles expected to work from the Knowledge System;

• the kinds of decisions those participants are expected to make or escalate; and

• the Engineering Leader or equivalent role accountable for ensuring that readiness is established for the intended work.

Not all information will be available at the outset. Apply proportionality to determine whether missing knowledge is material to the intended work and should be recorded as a readiness gap.

Back to top

3.2. Establish entry points and routing

A participant needs a clear place to begin. The entry point can be a root README.md, a product portal, an engineering service page, a repository landing document, or another maintained route appropriate to the organization. A document can state its own owner or approval status, and the entry point can route participants to the relevant authoritative knowledge when that route is not already obvious.

The entry point should answer three questions quickly:

1. What product or system am I working on? The participant should be able to identify the product purpose, accountable ownership, implementation location, and relevant scope.

2. Where is the authoritative knowledge for the decision I need to make? Product intent, architecture, security, reliability, operations, data semantics, and implementation guidance may have different sources and owners.

3. Who decides when the available knowledge is insufficient? The participant should be able to route a material question to the correct decision owner rather than infer an answer from incomplete context.

Routing will become more specific as the work becomes more specific. The Shared Knowledge System describes this as Progressive Context Loading. A contributor starts with a small amount of stable orientation and loads detailed context only when the current responsibility requires it.

The team should test human and AI access together. Documents should express their content in natural language and a format that qualified people can understand, while AI participants must be able to reach and apply the same relevant knowledge through their actual delivery tools. A security standard available through an internal web portal may be easy for an engineer to read but invisible to an AI coding agent operating only against the repository. Conversely, an AI retrieval connector may expose a document corpus without making its authority clear to a human. Readiness requires both forms of access to support the same responsible interpretation.

Back to top

3.3. Establish the engineering baseline

A usable engineering baseline gives a qualified engineer a supported way to inspect and meaningfully verify the current implementation. Development-environment setup forms part of that baseline. An action design research study in a Finnish software company characterized local development-environment setup and configuration as laborious, time-consuming, and error-prone, with a negative effect on developer experience.²

For the relevant product scope, establish a supported path to:

• obtain or inspect the source code and required implementation artifacts;

• understand the major repository or service responsibilities;

• identify required runtimes, package managers, developer tooling, accounts, permissions, and configuration;

• obtain approved secrets or credentials without recording secret values in the knowledge source;

• build, start, inspect, or otherwise exercise the relevant product state; and

• run a meaningful baseline verification, including known expected failures where they exist.

The required engineering baseline is product-specific. A local application may require a clean build and test run. A large distributed platform may require service access, representative integration tests, deployment tooling, and supported observability. The readiness requirement is reproducible or inspectable engineering evidence, with the supported path matched to the product's operating model.

Failures are useful readiness evidence. An undocumented dependency, a stale setup command, an unknown configuration key, a baseline test that fails unexpectedly, or a service that only one engineer knows how to start identifies a specific gap that can be assigned and resolved.

Back to top

3.4. Expose and record readiness gaps

Preparation will normally reveal more missing or inconsistent knowledge than the team should resolve immediately. Make those gaps visible before they become accidental implementation decisions.

A lightweight gap record is sufficient when it preserves the decision path:

Gap:
Affected subject:
Decision owner:
Required before:
Resolution evidence:
Status:

Required before is the key proportionality field. It states the work or decision that cannot responsibly depend on the missing knowledge. A disputed accessibility requirement might be required before a user-interface increment. An unclear service responsibility might be required before modifying the affected integration. A missing local setup step might be required before assigning implementation work that depends on that environment.

A gap that can materially change intended behavior, architecture responsibility, a standing obligation, acceptance evidence, or participant authority should be resolved before dependent work proceeds. A lower-risk gap that is unrelated to the planned work may remain open when it has a clear owner and required-before condition.

Back to top

4. Knowledge Areas and Decision Authority

Readiness can be established through different document taxonomies, provided the Knowledge System makes durable product knowledge discoverable under clear authority. The following knowledge areas are examined in separate Spec-First Hub papers.

The exact role titles vary between organizations, but accountability should follow decision authority.

Role-specific authority prevents a common failure in AI-assisted delivery. An engineer or AI agent may be the first participant to notice that two sources conflict, but discovery does not justify silently choosing a product interpretation, relaxing a security requirement, or redefining an architectural responsibility.

Back to top

5. Repository-Centered Reference Structure

The following structure is a repository-centered reference implementation of the readiness model. It is not the Specification-First Delivery Knowledge System itself, and it is not a mandatory taxonomy. Teams that use a wiki, document repository, knowledge graph, MCP server, or another maintained knowledge platform can apply the same responsibilities through their own entry point instead.

The structure is useful when a team wants its source repository to provide the primary entry point into durable product and engineering knowledge. Some files may contain the authoritative knowledge directly and state their owner or approval status. Others may route to an external governed source. A larger organization may keep most authoritative knowledge outside the code repository while using the repository only as a reliable routing layer.

Treat this structure as an initial starting point. A small product can keep several knowledge areas in compact files, while a growing product can split them into focused directories, records, or routing procedures when that improves ownership, discoverability, review, or AI context loading. The structure should evolve with the product while preserving clear entry points, authority, and routes to current knowledge.

The root files have different responsibilities:

The compact files in the reference structure can grow independently. For personas, a simple application may keep the complete set in docs/personas.md. A more complex product can evolve to docs/personas/ with separate governed persona records and an optional persona-directory Skill that helps design, structured-discussion, and specification work locate and load only the applicable personas. Personas and Actors develops that pattern in detail. Architecture, models, requirements, and other knowledge areas can be decomposed in the same way when separate ownership or retrieval becomes useful.

A practical root README.md should let an unfamiliar engineer answer, without relying on private team memory:

• What is this product and why does it exist?

• Who owns the product and the major technical responsibilities?

• Where are the authoritative product, architecture, specialist, and operational sources?

• What repositories, applications, services, or packages are relevant?

• What prerequisites, configuration, accounts, and permissions are required?

• What commands or supported procedures establish the current build, run, and baseline-verification state?

• Where should the participant go when the recorded information is insufficient?

A practical root AGENTS.md should then govern work after that orientation is established. It should route contributors to the applicable specifications and detailed instructions, state which implementation and verification rules apply, identify required evidence and Knowledge System updates, and define when the contributor must stop and escalate because the requested decision exceeds their authority.

The README and Governing Instructions have separate responsibilities. The README explains the product and establishes the working baseline. Governing Instructions govern how a contributor changes that baseline. The later Governing Instructions paper owns the detailed treatment of that mechanism.

This reference structure also demonstrates Progressive Context Loading. The root entry point remains small. A participant loads Product Intent when product purpose matters, architecture when system responsibility matters, security or reliability requirements when those concerns apply, and focused skills when a particular procedure is needed. The objective is to keep the relevant authoritative context reliably reachable while avoiding unnecessary loading of the complete Knowledge System into every task.

External knowledge, such as vendor API documentation or integration-partner documentation, can remain outside the repository. Rather than reproduce it automatically, use the relevant document or a local entry point to identify the external source, its subject, its owner, and the supported human and AI access path. This preserves one authority while still allowing the repository to function as a dependable starting point.

Back to top

6. Readiness Validation and Gap Management

An initial readiness baseline is adequate only when a qualified participant can use it. Validation should therefore exercise realistic tasks rather than review document presence alone.

Back to top

6.1. Unfamiliar-participant validation

Choose a qualified participant who has no prior product history, or simulate that condition through a participant who deliberately begins from the documented entry point rather than private team knowledge. Give the participant the same access routes that the real role would receive.

Representative tests include:

Joint human-and-AI validation must use the actual access paths that people and tools will use in delivery. Demonstrating that a human can open a document in a browser does not prove that the AI coding agent can retrieve it. Demonstrating that an enterprise search tool can retrieve a document also does not prove that the agent can distinguish the current authoritative source from an obsolete duplicate. The validation should establish both that a qualified person can understand the document and that the AI can reach and apply the same authoritative knowledge.

Back to top

6.2. Classify failures as readiness gaps

Every validation failure should produce a concrete gap rather than a general observation that documentation is poor.

Examples include:

A readiness owner can accept remaining gaps only when they do not block the intended work and each material unresolved gap has an accountable owner and a Required before condition. This keeps preparation proportionate without allowing unknowns to disappear into individual memory or implementation guesswork.

Back to top

6.3. Maintain readiness as the product changes

Readiness must be maintained as the product changes. Delivery increments change implementation, clarify product intent, revise architecture, add specialist requirements, expose undocumented assumptions, and generate new evidence. Material learning should converge back into the Knowledge System so that the next participant starts from the organization's current knowledge rather than reconstructing the previous increment.

Knowledge Convergence Across the Increment Lifecycle explains how material implementation learning is given an appropriate scope and authority before later work relies on it. Trusted Increments and Acceptance Evidence explains how specifications, implementation responsibilities, verification, and evidence support acceptance of a changed product state.

The readiness criterion remains the same after each material change: a qualified unfamiliar participant should be able to orient to the product, reach the authoritative knowledge and current implementation relevant to their responsibility, understand the constraints that apply, and route unresolved decisions to the correct authority. That capability is one practical expression of Capability Continuity.