Product Specification Standard

This standard defines the baseline structure that every product specification must include, regardless of venture. It applies to any product in any venture — a Shelfery app feature set, a Digital Products workbook, or a product in a future venture.

A venture may define its own, richer product specification template (for example, Digital Products may add workbook-specific sections covering sheet structure or formula conventions) but that venture-specific template must include every section below, not replace or omit any of them. A venture template extends this baseline; it does not substitute for it.

Required sections

1. Identity — product name, slug, owning venture, document_id.
2. Lifecycle status — current stage per docs/architecture/artifact-lifecycle.md (idea, draft, proposed, approved, maintained, deprecated/superseded).
3. Version — the specification's own version number, separate from any product release version.
4. Target customer — who this product is for, described concretely enough to be falsifiable (not "everyone").
5. Customer problem — the specific problem or need this product addresses for that customer.
6. Product promise — what the product commits to delivering, in plain terms.
7. Use cases — the concrete situations in which a customer would use this product, ideally as a short list.
8. Non-goals — what this product explicitly does not attempt to do, to prevent scope drift and to set honest customer expectations.
9. Differentiation — how this product differs from alternatives the target customer might otherwise use (including doing nothing, or a competing product).
10. Assumptions — anything the specification depends on being true, stated explicitly (see docs/standards/writing-and-documentation-standard.md).
11. Risks — known risks to the product succeeding (market, technical, legal, or otherwise), stated honestly rather than omitted.
12. Dependencies — other products, components, services, or decisions this product depends on.
13. Feature inventory — the concrete list of features/capabilities that make up the product.
14. Acceptance criteria — testable statements that determine whether the product (or a given feature) is considered done, per docs/standards/quality-assurance-standard.md.
15. Roadmap — planned future direction, clearly distinguished from what is already implemented (see docs/standards/commercial-claims-standard.md on not presenting roadmap items as current capabilities).
16. Support expectations — what level of support/maintenance customers can expect for this product (e.g., bug fixes only, active feature development, end-of-life plan).

What this standard does not dictate

This standard does not require a specific document length, a specific tone beyond writing-and-documentation-standard.md, or a specific technology or format for the product itself. Two products following this standard can look very different in substance while both being structurally complete.

Front matter

Every product specification uses the standard document metadata front matter (see docs/governance/document-metadata-standard.md), with document_type: specification.

---

Report an issue about this page