How to Build Stable, Traceable Product Facts

Hi, I’m Fan Mihua. This article starts with a small requirement change and explains why pages, flows, data, code, tests, and runtime evidence must evolve together.

1. Why can one sentence affect the whole product?

Changing lead conversion from always creating a customer to creating or reusing a customer with an optional opportunity affects duplicate checks, permissions, UI options, navigation, refresh behavior, failure recovery, and tests.

2. Product facts drift when each layer remembers a different version

A page can show the new option while the flow follows the old rule, data refreshes only partially, failure leaves half-completed state, and tests verify only a success message. The interface still works while the product is already inconsistent.

3. Share one product rule across every layer

Mihua Design uses Contract to preserve page responsibilities and cross-page flow rules in a machine-readable form. PRDs keep context, while _product.yaml and _flows.yaml preserve decisions that must be shared by pages, flows, code, and tests.

4. Connect decisions with ProductContractIR

ProductContractIR is compiled rather than edited directly. It connects flows, pages, stable interaction IDs, implementations, and verification evidence so the system can identify affected objects and missing work after a requirement changes.

5. A traceable change process

1. Update the owning product rule in Contract.
2. Use ProductContractIR to find affected pages, flows, operations, data projections, and checks.
3. Implement the change and verify the real browser and data result.

Technical chain

PRD → Contract v3 → Contract Loader → Contract Compiler → ProductContractIR → implementation and static checks → Runtime Evidence → VerificationRun

The goal is not to remove product judgment, development, or testing. It is to give every layer one current source of truth and a verifiable path from requirement to runtime result.