03 Work sample — an internal product spec
A public sample of an internal PRD I built — the product spec for an OCME tool (a
spec-as-database MCP server). It leaves out the security and access-model details, but what's
here shows how I frame a problem, hold scope, and write testable acceptance criteria. The full
spec is structured on twelve fixed sections — problem, vision, out-of-scope, principles,
constraints, goal, criteria, tests, and a decision log.
Problem framing
Specifications written as prose are designed for humans. In the era of agentic
engineering, specs need to be written for agents. When a coding agent reads prose,
it has no reliable way to know which statement is current and authoritative — so it makes
stale pulls (a superseded decision returned as co-equal), wrong-section pulls
(the same feature described in several places, blended), and read-time re-derivation
(intent re-inferred, and re-misread, on every read).
Scope discipline (anti-scope) Deliberately not:
- A project / issue tracker — it backlinks to execution but never owns tasks or status.
- The meeting or authoring tool — it serves only the approved record.
- A drafting assistant for new specs — authoring assistance is out of the tool entirely.
- A prose doc renderer — the structured record is the source of truth, no prose mirror.
- A general knowledge base — it governs functional specs only, not runbooks or notes.
Acceptance criteria authoring check_functional_spec returns exactly one row — the current version — from the materialized current-spec table.- The returned rule includes the atomic-rule fields: functional_definition, acceptance_criteria, anti_scope.
get_archive returns the prior version rows for that spec, ordered by version / effective_date.- Anti: the read path NEVER returns a superseded version, and never more than one current row for a given spec.
Architectural decision record Storage: git-authored YAML as the source of truth, a derived read-projection as
the serving layer — not the database as primary, not files as the serving layer.
Two independent design reviews converged on it; the deciding factor was audit and review,
not scale. The projection is a pure function of the approved commit, so the served record
can never silently drift from what was reviewed and merged.
Test strategy / definition of done | Check | How | Type |
| Serve one current row | call on a seeded spec; assert exactly one current row | integration |
| Atomic-rule fields | assert response carries definition + acceptance + anti-scope | integration |
| Archive retrieval | spec with ≥2 versions returns prior versions in order | integration |
| Anti: no stale reads | spec with archived versions returns 0 archived in current path | integration (anti) |