Wisent AI Product Guidelines

Turn a product promise into implementation-ready contracts in dependency order, without skipping decisions or forcing downstream teams to invent requirements.

This private repository is the shared operating standard for defining and reviewing Wisent products before implementation, integration, examples, and verification work begin.

Problem and intended users

Product work becomes expensive when implementation starts before the promise, scope, interfaces, operating constraints, and release contract agree. Teams then resolve the same ambiguity differently, and upstream changes silently invalidate downstream work. These guidelines provide one reviewable sequence for:

• Product owners defining the user outcome, scope, and commercial boundary.
• Engineers turning approved product decisions into interfaces and behavior.
• Reviewers checking that each stage is complete before downstream work starts.
• Operators confirming that deployment, credentials, cost, recovery, and support ownership are explicit.

Repository boundaries

This repository:

• defines documentation contracts, required decisions, prohibited shortcuts, and completion gates;
• establishes the dependency order between product artifacts;
• provides evidence-derived README practices and reference examples.

It does not define requirements for an individual product, replace product-specific documentation, enforce the gates automatically, or prove that a product implementation satisfies its contracts.

Core use cases

• Define a product: a product owner starts with an intended outcome and uses the staged contracts to produce an implementation-ready decision set without leaving scope to the implementation team.
• Reject an incomplete handoff: an engineer or reviewer maps a request to the current completion gate, identifies the missing product decision, and returns the work to the owning stage rather than guessing.
• Evaluate a product change: a maintainer changes an upstream promise, audience, boundary, or interface and follows the dependency chain to reopen every affected downstream artifact.
• Review operational readiness: an operator traces deployment, credentials, state, cost, failure, recovery, and support ownership before a release is treated as usable.

How the system works

Each stage consumes decisions made by the preceding stage. If an upstream decision changes, every affected downstream artifact must be reviewed again.

flowchart LR
    Promise["README contract"] --> Release["Release and versioning"]
    Release --> Onboarding
    Onboarding --> Core["Core functionality"]
    Core --> Integrations
    Integrations --> Examples
    Examples --> Verification["Tests and verification"]

The Hierarchy of Product Creation defines this dependency model in detail.

Quick start

• Read the Hierarchy of Product Creation to understand stage dependencies.
• Use the README Guidelines and evidence-derived best practices to draft the product contract.
• Apply the completion gate at the end of the guideline. Resolve every missing decision before continuing.
• Move to release and versioning only after the README contract is accepted, then continue through the documents in order.

Expected result: a reviewer can derive release, onboarding, implementation, integration, example, and verification requirements without inventing product scope or terminology.

Primary interfaces

• Human interface: the Markdown guidelines and their completion gates are canonical for product decisions and review.
• Reference data: the measured catalogs, capture tooling, and evidence contract live in wisent-ai/reference-engine; this repository consumes its findings and owns no reference data itself.

Canonical workflow

Stage	Guideline	Completion outcome
Product contract	README Guidelines	The chosen gateway, standard-product, or operated-product shape resolves every applicable reader decision without boilerplate
Release contract	Release and Versioning Guidelines	Artifacts, compatibility, channels, provenance, and rollback are defined
First success	Onboarding Guidelines	An intended user can reach a safe, observable result
Product behavior	Core Functionality Guidelines	Supported outcomes, invariants, state transitions, and failure behavior are specified
External boundaries	Integration Guidelines	Every supported integration has ownership, lifecycle, failure, and security contracts
Executable journeys	Examples Guidelines	Every supported application outcome has a canonical example
Reader documentation	Documentation Guidelines	The product docs site renders the shared layout and teaches ownership, operation, and recovery
Contract evidence	Testing Guidelines	Observable contracts are defended at the appropriate boundaries

Reference evidence

• Adaptive README Template provides three copyable shapes and conditional modules instead of one mandatory outline.
• README Best Practices explains the patterns worth reusing and the popular patterns Wisent deliberately rejects.

Operating model

The repository is documentation-first and has no runtime service. Durable state is the versioned Markdown, source snapshot, and analysis data in Git. Changes to an earlier stage require review of affected later documents. Reference snapshots remain attributable to their source repositories and retain their upstream license terms.

Status and support

• Status: internal working standard for Wisent-owned products.
• Visibility: private repository.
• Canonical branch: main.
• Compatibility: main is the current standard; product repositories should record the revision they adopted when reproducibility matters.
• Distribution: Git repository only; there is no packaged or hosted runtime.
• Corrections and proposals: open an issue in wisent-ai/product-guidelines.
• Sensitive reports: do not place credentials or undisclosed product vulnerabilities in an issue; this repository does not currently publish a dedicated security-reporting policy.
• License: no repository license is present; treat original Wisent material as proprietary. Imported README snapshots remain governed by their respective source licenses.