Specification-First Delivery

Framework guidance

Adopting Specification-First Delivery

Adoption begins by making one type of change easier to understand and control. Choose the path that best matches the work in front of you, then use it to build a Specification System that keeps intent, decisions, implementation, and evidence connected.

Four practical starting paths

Begin with the software you actually need to change.

Use these flows to establish a trustworthy first delivery path. They describe a minimum sequence, not a fixed process. Add depth to each artifact when consequence, novelty, ambiguity, or dependencies warrant it.

Scenario 1

Greenfield development

A new product or service is the clearest opportunity to establish shared language and working agreements before accidental conventions accumulate. Start with a small, valuable increment, but design the foundations so later contributors can understand the decisions that shaped it. Use the first increment to test both the product idea and the conventions that will guide later change.

Greenfield delivery flow

Establish the system before the first trusted increment.

  1. 1

    Set outcome and authority

    State the intended outcome, users, scope, non-goals, material risks, and decision owners before choosing architecture or generating implementation work.

  2. 2

    Create a shared language

    Build a concise glossary, identify actors and use cases, and describe normal paths, exceptions, rules, and acceptance conditions. Mark assumptions awaiting owner decisions.

  3. 3

    Shape constraints and interfaces

    Capture system context, major components, data meaning, external contracts, security and operational needs, and quality attributes. Keep architectural alternatives and their rationale visible.

  4. 4

    Put working knowledge with code

    Create repository structure, governing instructions, templates, test conventions, and documentation ownership. Check the material in with code so one change path preserves its history.

  5. 5

    Deliver and learn one increment

    Turn the first slice into clearly scoped jobs, implement and verify it against the specification, then record acceptance evidence, deviations, and lessons for the next increment.

Scenario 2

Brownfield development

For an existing codebase, the first task is not to describe everything. It is to establish enough reliable context for a safe next change and make uncertainty visible. Treat current code as evidence alongside tests, operations, documentation, and experienced people. The initial pilot should leave the codebase safer to change than it found it.

Brownfield delivery flow

Create a safer path for the next change, then improve it incrementally.

  1. 1

    Establish a workable baseline

    Recover or confirm build, test, deployment, and rollback paths. Identify owners, critical dependencies, operational constraints, and the change most suitable for a first pilot.

  2. 2

    Map the available evidence

    Compare code, tests, schemas, interfaces, runbooks, tickets, and stakeholder knowledge. Record contradictions and gaps instead of treating a single source as automatically authoritative.

  3. 3

    Reconstruct the change scope

    Describe the behavior to change, the behavior to preserve, affected data and contracts, failure modes, and acceptance conditions. Escalate unresolved meaning to the right owner.

  4. 4

    Install proportionate working rules

    Add repository guidance, decision records, specification templates, and evidence locations only where they support the change. Do not codify every existing habit or debt.

  5. 5

    Deliver a traceable pilot

    Execute a clearly scoped increment, link implementation and verification to its specification, and use the review to refine the knowledge base before selecting the next improvement.

Scenario 3

Rewrite an existing system

A rewrite is not an instruction to reproduce old code in a new technology. It is a decision to establish what behavior, data meaning, controls, and operating expectations should survive. Specification distillation gives the new system a reviewable starting point. Do not ask the build team to settle business contradictions through implementation choices.

Rewrite delivery flow

Distill what matters before rebuilding any part of the system.

  1. 1

    Define the replacement decision

    State the business outcome, target scope, constraints, cutover expectations, and reasons a rewrite is preferable to incremental replacement, replatforming, or retirement.

  2. 2

    Collect and distill evidence

    Examine requirements, code, tests, data, interfaces, production behavior, incidents, and practitioner knowledge. Produce a reviewable set of claims with associated confidence levels and supporting evidence.

  3. 3

    Classify existing behavior

    Ask accountable owners to decide what to preserve, correct, replace, retire, defer, or leave unresolved. Existing implementation is evidence, not automatically the target specification.

  4. 4

    Specify the target and migration

    Create the target behavior, architecture, data, contract, operational, security, compatibility, and migration specifications. Define equivalence evidence, rollback limits, and staged cutover conditions.

  5. 5

    Rebuild by accepted slices

    Deliver replacement increments through normal specification-led work, compare them with the approved target and legacy obligations, then retain evidence before expanding or decommissioning.

Scenario 4

Customize vendor or open-source software

Customizations often become invisible until the next upgrade breaks them. A specification set makes the organization’s additions, dependencies, and accepted trade-offs explicit, so the team can deliberately rebuild, replace, or retire them when the vendor baseline changes. The aim is not to preserve every modification, but to make each retained decision reproducible.

Customization delivery flow

Make custom behavior reproducible across upgrades.

  1. 1

    Frame the upgrade and scope

    Identify the vendor release, supported extension points, required business outcome, customization owners, compatibility obligations, and the operational window available for the upgrade.

  2. 2

    Inventory custom behavior

    Trace configuration, code extensions, data changes, integrations, reports, access controls, and workarounds. Link each item to the user need, owner, and evidence of current behavior.

  3. 3

    Decide what should survive

    Classify each customization as preserve, adapt, replace with vendor capability, retire, or defer. Capture conflicts between the new baseline and existing business or technical constraints.

  4. 4

    Specify the rebuild path

    Document extension points, adapters, migration steps, test cases, data conversion, fallback, and acceptance criteria. Keep custom code separate from the vendor baseline where practical.

  5. 5

    Upgrade with evidence

    Apply the upgrade in a controlled environment, verify vendor and custom behavior together, accept the result with evidence, and update the specification set for the next release.

Use the smallest path that produces trustworthy learning.

The same discipline applies in every scenario: make judgment explicit, assign each decision an owner, define execution scope and authority, and accept only with evidence. Once one path works, improve the next based on what the organization has learned.

Review the Specification-First Delivery overview