Move from a diagram insight to a written specification linked to the model.
Exploration surfaces decisions: a missing boundary, an unclear responsibility, a relationship that needs rules. This workflow turns that insight into a specification anchored to the model.
The flow
Find the object in Explore
Navigate to the object or relationship the decision is about.
Capture the decision
Create or open a specification page for that area.
Link to the model
Embed the relevant model view or reference the object so the spec stays anchored.
Add detail
Document constraints, contracts, and rationale in MDX.
Keep it connected
Update the spec when the model changes so the two stay in agreement.
Anchoring specs to objects
| Technique | Result |
|---|---|
| Embed a model diagram | Readers see the structure in context |
| Reference object paths | Specs point to real, navigable objects |
| Attach artifacts | Contracts (OpenAPI, ERD) live next to prose |
Specs and model reinforce each other
A spec anchored to objects is easier to keep accurate, and a model linked to specs is easier to understand. The connection is the value.
Write the spec while exploring, not later. The reasoning is clearest at the moment the question appears on the diagram.
Last updated on