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.