Specification-First Delivery

The Knowledge System

Write specifications from knowledge your organization can trust.

The Knowledge System is a first-class artifact of Specification-First Delivery (Spec-First Delivery). It ships product, domain, engineering, quality, security, and operational knowledge with software delivery. It preserves the durable product knowledge that another qualified participant should not have to rediscover before making a material change.

Components of the Knowledge System to ship with the software.

Gather the knowledge a specification writer needs before defining the work.

No change needs every item below. The people responsible for the change should identify which knowledge is relevant, which sources are authoritative, and which questions still require a decision.

  1. Product and user understanding

    Explain the outcome the product needs to create and who the change is for.

    • Product intent, priorities, expected outcomes, and non-goals
    • Personas, user needs, use cases, journeys, and exceptions
    • A glossary of domain terms, business rules, and data meaning
    • Product-specific methods, including calculation methodology where it affects behavior

  2. Organizational context

    Show how the system supports the business and which people are accountable for its meaning.

    • The business function, process, service, or capability that the system supports
    • Stakeholders, decision owners, and the responsibilities each function holds
    • Policies, legal obligations, controls, and operational commitments that affect the change
    • Known risks, incidents, support concerns, and production learning

  3. Architecture and interfaces

    Describe the current system well enough to make an informed technical decision.

    • System responsibilities, architecture decisions, and protected areas
    • Data models, lifecycle rules, compatibility expectations, and migration requirements
    • External interfaces, contracts, dependencies, sequencing, and error behavior
    • Existing tests, observability, deployment, rollback, and recovery information

  4. Constraints and restrictions

    Make explicit what the proposed work must respect and what it must not change.

    • Security, privacy, reliability, performance, accessibility, and operational requirements
    • Protected behavior, compatibility obligations, and parts of the system that must remain unchanged
    • Approved technology choices, repository instructions, engineering standards, and delivery constraints
    • Acceptance criteria and the evidence an accountable role needs before accepting the result

  5. Discussion and decision history

    Keep the reasoning that shaped the current specification available for later work.

    • Discussion documents that record the request, questions, options, assumptions, and unresolved issues
    • Past decisions, rejected alternatives, approved deviations, and their rationale
    • Earlier specifications, acceptance evidence, implementation history, and learning from delivery
    • Links between the current change and the knowledge it relies on

  6. The code

    The code is the ultimate source of truth for the system’s implemented behavior.

    • AI coding agents need access to the code to inspect the behavior in place and the established implementation patterns
    • AI coding agents need access to the code to identify dependencies and assess the likely impact of a proposed change
    • Code informs discussion, requirement analysis, and specification writing. Without it, stated requirements may be impossible to implement.
    • When an AI coding agent writes specifications from the full Knowledge System, including the codebase, it can compare the intended outcomes with the current system and help create implementable specifications

Writing specifications

Effective specifications reduce guesswork before it becomes code.

These practices apply to product owners, product and project managers, business analysts, development leads, architects, software engineers, QA engineers, security engineers, reliability engineers, and anyone else who writes material requirements or technical direction.

  1. Ask AI until it identifies no further material questions.

    Use AI to examine the request against the relevant knowledge. Ask it to surface normal and exception paths, assumptions, missing information, conflicts, dependencies, and acceptance questions. The goal is to minimize guesses before anyone starts implementation.

  2. Update the Knowledge System as discussion reveals new information.

    Record newly confirmed information in the appropriate knowledge source. When an update belongs to another function’s document, ask its owner to review it. Direct questions about product behavior, data, security, reliability, operations, or architecture to the colleagues responsible for those decisions.

  3. Review the specification line by line.

    The accountable reviewers examine every statement for accuracy, completeness, scope, constraints, protected behavior, dependencies, and acceptance conditions. They remove ambiguity, identify unresolved decisions, and record who must decide them.

  4. Keep each specification in its proper scope.

    Functional specifications describe required behavior, users, business rules, exceptions, and acceptance criteria while avoiding unnecessary technology choices. Non-functional specifications may state security, reliability, performance, operational, and technical requirements, but should not make implementation design decisions that belong to software engineers unless those decisions have been explicitly reviewed and assigned.

  5. Maintain the history of major technology decisions.

    Record the major technology choice, alternatives considered, decision owner, rationale, consequences, and any conditions that would require the decision to be revisited. Later writers and reviewers should not need to rediscover why the organization chose the current approach.

Specifications become knowledge

An approved specification is reusable organizational knowledge.

Reviewed specifications join the Knowledge System. They help engineers plan implementation, help AI understand the work it is authorized to perform, help reviewers assess conformance, and help product and quality roles decide whether the result meets the agreed conditions.

After delivery, the resulting code, decisions, evidence, deviations, and operational learning should update the same system. That continuity lets another qualified contributor continue the work without reconstructing essential meaning from private memory or source code alone.

Knowledge and specifications prepare work. The Workflow shows how the work moves through delivery.

Follow the Workflow to see how reviewed knowledge and specifications connect to execution, verification, acceptance, and learning returned to the Knowledge System after delivery.

Explore the Workflow page