Annotation
A free-text note attached to a Scenario by a Member — used to add context, decisions, or caveats that the code alone cannot express.
A Scenario captures the behaviour itself. An Annotation captures everything around it — the design rationale, the customer who asked for the behaviour, the edge case the team chose not to support yet, the workaround engineering put in until a refactor lands. Things the code does not say on its own.
Annotations belong to a single Scenario, persist across Syncs, and never get overwritten when the underlying code changes. They open from a panel on the Scenario in the UI, and any Member of the Organisation can add one — including Viewers, since commentary is not the same as editing the spec. Once posted, an Annotation cannot be edited or deleted; if a note needs correcting, post a follow-up.
The point of Annotations is to keep the spec honest about its own limits. The code is one source of truth; the team's tacit knowledge is another. An Annotation is the smallest possible bridge between the two without re-introducing a parallel doc.
Related terms
- SPEC
Scenario
A single plain-language description of how a product behaves in a specific situation. The atomic unit of a Specsight spec.
- CONCEPT
Living Documentation
The mechanism behind product observability: a spec derived from the code rather than written separately, so it moves with the product instead of falling out of sync.
- OPERATIONS
Sync
The release-triggered update to a Specsight spec. Fires automatically every time code lands on the tracked branch, touching only the scenarios that release changed.