Pre-Flight Spec Authoring

also known as Spec-Driven Development (authoring phase), SDD authoring, Pre-Implementation Specification

Before any code is generated, author a multi-pillar spec and have the agent critique it for ambiguity and edge cases, so that the loop executes against a reviewed target rather than a fresh prompt.

Context

A team is about to put a coding agent to work on a non-trivial change. The team has a shared issue tracker, source control, and at least one capable agent available for both spec critique and implementation. Time spent in front of the first agent run is cheap compared to the cost of cleaning up agent-written code that compiles but is wrong in shape.

Problem

Agents handed an underspecified prompt produce code that runs but does not match what the team needed: assumptions get baked in silently, edge cases get skipped, and the team discovers the gap during review or in production. Quoting the Norwegian source: agents 'ignorerer instruksjoner, de produserer kode som fungerer men ikke nødvendigvis er vedlikeholdbar' — they ignore instructions and produce code that works but is not necessarily maintainable. The team needs a way to do the thinking up front and to make the agent challenge that thinking before it writes code.

Forces

Spec authoring is up-front cost; the team must believe it pays back in less rework.
The agent that critiques the spec must be allowed to push back rather than rubber-stamp it.
The spec must live somewhere durable — the issue tracker or repo — so later loop iterations and human reviewers share the same target.

Example

An engineer picks up an issue to add idempotency keys to a payment endpoint. Rather than prompt the agent directly, they fill in a five-pillar template in the tracker: context (why retries currently double-charge), requirements (header name, storage TTL, response shape on replay), constraints (no schema migration this sprint, must work behind the existing rate limiter), examples (a curl request and the expected replayed response), definition-of-done (a new integration test plus updated API docs). They run a 'critique this spec' pass with the agent, which flags three gaps: behaviour on key collision across tenants, behaviour when the original request is still in flight, and whether the key should be required or optional. The engineer answers each in the spec, then starts the implementation loop. The loop converges in fewer iterations because the agent stops asking the same questions every turn.

Diagram

flowchart TD Author[Human authors spec] --> Pillars[(Five pillars: context, requirements,\nconstraints, examples, definition-of-done)] Pillars --> Critique[Agent critiques spec\nfor ambiguity + edge cases] Critique --> Gaps{Gaps found?} Gaps -- yes --> Author Gaps -- no --> Persist[Persist spec in issue tracker] Persist --> Loop[Implementation loop reads spec]

Solution

Therefore:

Author the spec along five pillars: context (why this work, what surrounds it), requirements (what must be true), constraints (what must not be done), examples (concrete inputs and outputs or code shapes to mirror), and definition-of-done (the gate the loop must pass). Then run an explicit model-critique step in which the agent reads the spec and lists ambiguities, missing edge cases, internal contradictions, and unstated assumptions; the human resolves each before code generation begins. Store the finished spec in the issue tracker (or an equivalent durable artefact store) so every later iteration and every human reviewer reads the same target. Only then hand the spec to the implementation loop.

What this pattern forbids. No code-generating step may begin until the spec has been authored along the five pillars, critiqued by the agent, and persisted in the durable artefact store; loop iterations read the spec as their authoritative input rather than the free-form prompt that started the session.

And the patterns that stand alongside it, or against it —

composes-withSpec-Driven Loop★— Run the same prompt against a fixed spec in a deterministic outer loop until the spec is satisfied.
composes-withSpec-First Agent★— Drive the agent loop from a human-authored specification document rather than free-form prompts.
complementsGoal Decomposition★★— Decompose a goal into sub-goals recursively until each leaf is directly actionable.
complementsPlan-and-Execute★★— Plan all the steps once with a strong model, then execute each step with a cheaper model under the plan.
complementsTodo-List-Driven Autonomous Agent★— Have the agent author a plan file (e.g. todo.md) early in the run, tick items as it completes them, and re-inject the remaining plan into context; the file is durable plan and working memory.
complementsAgentic Context Engineering Playbook·— Treat the agent's system prompt and long-lived memory as a structured, item-addressable playbook that evolves through small delta updates from a Generator/Reflector/Curator loop, so accumulated tactics resist the context collapse that monolithic rewrites cause.
complementsStrategic Preparation Phase★— Mandate an explicit problem-space representation step before the agent attempts solutions, mirroring how expert humans build a mental model of constraints and dependencies before solving.