Demo and Spec Alignment
Demo and spec alignment is the practice of keeping prototype or demo behavior consistent with documented product intent, while updating the specification explicitly when a demo reveals a better workflow.
Why this matters
Demos are useful because they make workflows concrete. They are risky because people often start treating visible behavior as approved product truth even when the underlying documentation was never updated.
Recommended authority order
- product specification
- implementation guidance
- current-state documentation
- demo or implementation behavior
- validation and tests
This order does not mean demos are unimportant. It means demos should be interpreted within a documented decision system.
Healthy demo usage
Use demos to:
- expose workflow problems
- reveal usability issues
- test assumptions with users
- support explanation for stakeholders
Do not use demos as silent replacements for product decisions.
When the demo should lead
If the demo reveals a clearly better workflow, the team should:
- review the change intentionally
- update the relevant specification and docs
- adjust validation or review expectations
In other words, the demo may inspire the next decision, but the updated decision should still be documented.
Let Books context
The Let Books repository already distinguishes between canonical documentation evidence and implementation status for public writing. That is a useful guardrail because it prevents prototypes from becoming accidental editorial authority.