Specs and the design-before-implementation discipline

2026-03-02 01:28:25.760Z

A Spec is a typed design artifact that describes a
specific slice of the Event Model in enough detail
to implement from. Specs are written before code.
This is not a preference — it is the discipline that
makes NEXUS work.

What a Spec Is

A Spec takes a slice from the Event Model and makes
it actionable. Where the Event Model shows the shape
of the system — commands, events, projections, and
their relationships — a Spec describes a specific
slice in enough detail that an implementer, human or
AI, can produce correct code from it without
ambiguity.

A Spec contains:

The slice it describes — which command, event,
or projection this spec covers, linked to the
Event Model element
The path or paths it serves — which paths
traverse this slice, linked to the path topics
in LOGOS
Inputs — what the slice receives. For a
command: the command fields and their types and
constraints. For a projection: which events it
consumes and what it extracts from them.
Outputs — what the slice produces. For a
command: the event or events produced and their
fields. For a projection: the shape of the
derived state.
Rules and constraints — the logic within
the slice. Validation rules, business rules,
error conditions, edge cases.
Example data — the concrete values from
the paths that traverse this slice. The spec
is not abstract — it is grounded in the example
data that flows through it.
Acceptance criteria — how you would know
the implementation is correct.

The Workflow

A Spec topic in LOGOS moves through defined states:

Draft — being written. Not ready for review.
The slice is understood well enough to start
specifying but the spec is not yet complete.

Under Review — complete enough to review.
Feedback is being gathered. The spec may change
based on review. It is not yet safe to implement
from.

Approved — reviewed and accepted. The spec
is the basis for implementation. An approved spec
is an input to AI-assisted code generation. It
should not change without moving back through
review.

Linked to Implementation — implementation
exists and is linked back to this spec. The loop
is closed. The spec and the code it produced are
connected in both directions.

State transitions are explicit events — not just
edits to the topic. Each transition is timestamped
and attributed. The history of a spec's journey
from Draft to Linked to Implementation is part
of the permanent record.

Design Before Implementation

The discipline is absolute: specs are written
before code. Not alongside code. Not after code
as documentation. Before.

This discipline exists because of what gets lost
when it is violated. When implementation precedes
specification, the design decisions that shaped
the code exist only in the developer's head at
the moment of writing. They are never made
explicit. They are never reviewed. They cannot
be questioned, improved, or reused. Six months
later they are gone.

When specification precedes implementation, every
design decision passes through a moment of
explicit articulation. Writing the spec forces
clarity that implementation alone does not require.
Gaps and ambiguities that would have been resolved
implicitly during coding — in ways that might not
be correct — are instead resolved explicitly,
visibly, before any code is written.

The spec is not documentation of the implementation.
The implementation is a rendering of the spec.

Specs and AI Implementation

An approved spec is the primary input to
AI-assisted code generation within NEXUS. This
is not incidental — the spec format is designed
with AI consumption in mind.

An AI given an approved spec has:

Unambiguous inputs and outputs
Explicit rules and constraints
Concrete example data to validate against
Acceptance criteria to verify against

This is everything needed to implement correctly.
The AI does not need to infer intent, guess at
edge cases, or make design decisions. Those are
resolved in the spec. The AI renders the spec
into code.

The language-agnostic nature of a well-formed
spec means the same spec can be rendered into
F#, JavaScript, or any other target language.
The spec describes what — the AI and the target
language determine how.

See: NEXUS → AI-assisted implementation.
See: NEXUS → Language-agnostic design — one
model, many implementations.

Specs and Example Data

Example data from paths flows into specs. The
concrete values that a path carries through the
Event Model appear in the spec for each slice
that path traverses. This grounds the spec in
reality — the spec is not specifying an abstract
slice, it is specifying the slice as it behaves
for these concrete cases.

The example data in the spec becomes the test
data for the implementation. The acceptance
criteria are verified against the example data.
If the implementation passes the example data
cases, it implements the spec correctly for all
designed paths.

See: NEXUS → Paths as first-class artifacts.

Specs in LOGOS

Each spec is a topic in the relevant project
category in LOGOS. Specs are linked bidirectionally:

To the Event Model element they describe
To the paths that traverse them
To the implementation they produced

A spec topic is never an island. It is always
connected — to the design above it and the
implementation below it. That connectivity is
what makes the system traceable from intent to
running code.

See: LOGOS → Requirements → Spec-to-implementation
linking.

Acceptance

A developer or AI given only the spec — with no
other context — can produce a correct
implementation. The spec is sufficient. If
additional context is required to implement, the
spec is incomplete.