Skip to content

DD-DIGPROD-ADR-0003: Product Specifications Live in the Implementation Repository, Not in Per-Product Governance Templates

Status

approved — decided directly by the Founder on 2026-07-27.

Date

2026-07-27

Context

ADR-0014 settled that venture implementation code lives in a separate, venture-owned repository (devonside-labs for Digital Products) rather than in this governance repository. It did not, however, settle where a product's specification lives once that implementation repository exists — product-artifact-lifecycle.md (stage 3) still describes the specification gate as producing "a formal product specification under products/<slug>/, built from products/_template/" in this repository.

In practice, for the venture's first product (llc-accounting-tracker, built under the working name schedule-c-workbook), that is not what happened. The Founder supplied a detailed requirements prompt directly (captured verbatim as ventures/digital-products/products/llc-accounting-tracker/assets/source-requirements-2026-07-12.md), and the real, living specification accumulated in the devonside-labs implementation repository — products/llc-accounting-tracker/docs/implementation-note.md, plus that repository's docs/ai/ knowledge base (decisions, glossary, open questions) — while this repository's scaffolded template documents (product-requirements.md, acceptance-criteria.md, commercialization-plan.md, the product's decisions/ subfolder) remained unfilled (document_type: template, status: draft, bracketed placeholders throughout). This divergence was tracked as an open question in devonside-labs's docs/ai/open-questions.md: should the governance-repo templates be backfilled to match, or should the implementation repository's docs be treated as sufficient going forward?

Decision

This governance repository defines the venture — its policy, standards, brand, and cross-product strategy. It does not hold individual product specifications once that venture has an implementation repository. For Digital Products, whose implementation repository is devonside-labs (per ADR-0014), a product's actual specification — requirements, decisions, implementation notes — lives with the product in that repository, not in this repository's per-product template folder.

Concretely:

  • llc-accounting-tracker's governance-repo template documents (product-requirements.md, acceptance-criteria.md, commercialization-plan.md, decisions/) are not being backfilled. They remain as unfilled templates and should not be read as an indication that specification work is outstanding — the real specification lives in devonside-labs's products/llc-accounting-tracker/docs/implementation-note.md and that repository's docs/ai/ knowledge base.
  • This is the general pattern going forward, not a one-off exception for this product: a Digital Products product's specification lives entirely in devonside-labs from the start. This repository's products/<slug>/ folder retains only what is genuinely venture-registry-level (product.json, and any pre-implementation research artifacts such as the source-requirements capture above) — not a parallel copy of the spec itself.
  • product-specification-standard.md's 16 required baseline sections still apply — this decision changes where a compliant specification document lives, not whether one is required or what it must contain. A product's specification, wherever it lives, must still be checkable against that standard's required sections.

Consequences

  • Benefit: removes a standing duplication risk. A spec that could live in two repositories (a governance-repo template plus the implementation repository's real docs) would drift, and "which one is authoritative" would become its own open question per product — this decision forecloses that ambiguity for every future product, not just this one.
  • Benefit: matches actual behavior instead of leaving a stale gate description on record; product-artifact-lifecycle.md stage 3 previously described a step that the venture's first product did not actually follow.
  • Cost: this repository's product-specification-standard compliance is no longer directly auditable from inside this repository alone for any Digital Products product — checking llc-accounting-tracker against product-specification-standard.md's 16 sections now requires opening the devonside-labs repository. Anyone auditing venture-wide specification compliance needs to know to look there, not just here.
  • Cost: this repository's products/_template/ scaffold (product-requirements.md, acceptance-criteria.md, commercialization-plan.md, decisions/README.md, and the other template files) is no longer the thing a new product actually fills in going forward. The scaffold's continued purpose is narrowed to whatever pre-implementation research artifacts a product accumulates before an implementation repository exists for it (see Follow-up Actions).

Alternatives Considered

  • Backfill the governance-repo templates to match devonside-labs's real spec. Rejected: this would create exactly the duplication this decision is meant to avoid — two copies of the same spec, in two repositories, that would silently drift the first time either one is updated without the other.
  • Keep the question open per product, decided case by case. Rejected: the venture's only product so far already resolved this in practice (spec lives in devonside-labs); leaving it open just delays writing down what already happened, and risks a future product deciding differently with no stated default to follow.
  • Move venture-level policy and standards into the implementation repository instead, eliminating this repository's role for Digital Products entirely. Rejected: out of scope for this decision and inconsistent with ADR-0014's own framing — this repository stays the source of truth for policy/standards/brand across ventures; only per-product specification content moves.

Follow-up Actions

  • Update product-artifact-lifecycle.md stage 3 so it no longer describes the specification gate as producing a filled template under products/<slug>/ in this repository — done as part of this same change.
  • ~~Update llc-accounting-tracker/product.json's status_note to reflect that the template documents are an intentional non-backfill, not pending work~~ — done as part of this same change; superseded hours later the same day when ADR-0017 moved product.json itself into devonside-labs and removed this repository's copy entirely.
  • Update context-loading.md and role-routing.md so their pointers to ../../products/<slug>/ for a product's spec correctly describe that, for a product with an implementation repository, the spec is there — done as part of this same change.
  • ~~If a future Digital Products idea reaches the specification stage before an implementation repository exists for it, products/_template/ remains available for that interim state; this ADR does not resolve what happens to that interim content once the implementation repository is created (migrate it over, or treat it as superseded by the fresh implementation-repo spec) — left as a genuinely open question for whenever that scenario first occurs.~~ Resolved later the same day by ADR-0017: there is no interim scaffold at all. products/_template/ and products/llc-accounting-tracker/ were both removed; a pre-implementation-repo product idea stays an unbuilt backlog entry (now in devonside-labs' docs/ai/product-backlog.md) until implementation begins. product.json itself also moved — it now lives with the product in devonside-labs, not in this repository.

Report an issue about this page