Review a question, not every file at once
Begin with a behavior you need to trust: who can invoke a sensitive operation, what prevents duplicate work, or how a failed job is recovered. Use the feature and architecture views to locate the responsible components and follow their relationships.
This gives the review a path through the system. It does not replace reading code, running tests or observing production. It helps you identify which evidence would answer the question and where a missing connection or unclear responsibility deserves attention.
Connect intent to implementation
Open Specification and read the relevant requirement, its acceptance criteria and the records linked to it. Then follow those records into the implementation views. Check that the component expected to enforce the rule has the data and authority needed to do so.
For example, “a retry must not create a second order” is an obligation. A stable command identity, a durable uniqueness mechanism and a tested retry path may support it. A paragraph saying “idempotent” is not enough to establish that behavior.
Use several representations of the same thing
A service may appear in architecture, a feature flow, a message sequence and runtime placement. These are different questions about the same canonical object. Moving between them helps reveal mismatches: a required recovery step without an owner, or a table whose writers are absent from the diagram.
Use the working-plane artifact list and anchors to keep exact objects in context. Back and Forward preserve a trail while you inspect detail. Narrowing to one feature can make a large product review manageable without splitting the specification into unrelated files.
Keep claim strength visible
Read the status and evidence associated with a finding. Source-inspected means the author inspected the cited source; it does not automatically mean deployed. Proposed architecture should remain visibly proposed. Synthetic demonstration data should not be treated as a real implementation.
Review coverage notes alongside the diagrams. A specification that admits an unknown deployment boundary can guide the next investigation. A complete-looking picture with no source revision is harder to trust, even when its layout is polished.
Update the explanation when the product changes
During separately authorized implementation work, ask the agent to update affected records, relationships, requirements and evidence with the code change. Review the specification against the new source revision and export the updated file.
The free reader does not watch your repository or synchronize changes automatically. Treat the file as a versioned account of the product. Use the staged authoring process for systematic investigation, and the handoff workflow to carry the explanation to another person or device.
Explore a fictional example, or open your own .ospec file locally.
Open 1view →