Define once, cite everywhere

Juan G Carmona — Fri, 21 Aug 2026 08:55:24 +0000

Run this on any repo doing spec-driven development:

grep -rn -i "refund" openspec/specs

Mine returned:

billing/spec.md:4:  Refunds are issued for purchases made in the last 30 days.
checkout/spec.md:4: Customers can request a refund within 30 days of delivery.
support/spec.md:4:  If the order is less than a month old, offer a refund.

Same rule, three specs, three wordings — and two meanings. 30 days from purchase is not 30 days from delivery. Nobody decided that fork. A coding agent paraphrased it into existence, and no human caught it, because nobody reads specs anymore — only agents do. As truth.

We fixed this in code decades ago: don't repeat yourself. Specs never got the memo.

The fix: define the rule once, and let every spec cite it — one line, carrying a content digest:

Refunds follow BR-REFUND-001. {pdac:cite id="BR-REFUND-001" digest="sha256:b5c5…"}

When the rule changes through your normal review flow, one command flags every citing spec — file and line, no grep:

$ prodshape citations verify
stale  BR-REFUND-001  openspec/specs/billing/spec.md:4
stale  BR-REFUND-001  openspec/specs/checkout/spec.md:4
stale  BR-REFUND-001  openspec/specs/support/spec.md:4

Put it in CI and stale product knowledge stops being invisible. Specs get shorter, forks become impossible, drift becomes detectable.

Full 30-second demo (real output, @prodshape/cli@0.12.0, no setup): .https://jgcarmona.com/en/define-once-cite-everywhere/.

The idea behind it: Product Definition as Code — one versioned product model that specs and agents cite instead of re-derive, upstream of whatever SDD tool you use.

Try the grep on your own specs and count your forks. Found one? Tell me in the comments — I'll help you set this up in 15 minutes.

DEV Community: Juan G Carmona

Define once, cite everywhere