DEV Community

Cover image for Define once, cite everywhere
Juan G Carmona
Juan G Carmona

Posted on Originally published at jgcarmona.com

Define once, cite everywhere

#ai #llm #opensource #productivity

Run this on any repo doing spec-driven development:

grep -rn -i "refund" openspec/specs
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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…"}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)