Vocabulary, defined
Definitions of the words Specsight uses — scenario, feature, sync, drift — and the methodologies that came before
Table of contents
Concepts
The foundational ideas product observability rests on — what it is, what it produces, and the principles behind it
- 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.
- CONCEPT
Product Observability
Continuous insight into how a product behaves and changes, release by release — the way infrastructure observability (Datadog, Sentry) watches your systems, pointed at the product itself.
- CONCEPT
Product Specification
A written description of how a product behaves — feature by feature, scenario by scenario. Distinct from a technical spec, which describes implementation.
- CONCEPT
Single Source of Truth
A canonical, authoritative version of information that everything else defers to. For product behaviour, the only true source of truth is the code itself.
In a spec
What you read when you open a Specsight spec — features, scenarios, the Context/Action/Outcome triplet, and the shapes scenarios take
- SPEC
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.
- SPEC
Changelog
A chronological record of what changed in a product, feature, or scenario over time. In Specsight, one running changelog covers the whole product, filterable down to a single Feature.
- SPEC
Context, Action, Outcome
A structured format for describing product behaviour. Precise enough to be unambiguous, plain enough for anyone on the team to read — without the machine-oriented syntax of BDD.
- SPEC
Edge Case
A scenario that describes unusual but valid behaviour — the conditions at the edges of what the feature supports. Often the source of support tickets.
- SPEC
Error Scenario
A scenario that describes how the product responds when something goes wrong — invalid input, failed validations, blocked actions, or system-level failures.
- SPEC
Feature
A logical grouping of scenarios that represents a meaningful unit of the product — like “Document Upload” or “User Authentication.” Features form the structure of a Specsight spec.
- SPEC
Feature Map
A visual map of how features in a product depend on one another. Used to see the blast radius of a change before it ships.
- SPEC
Happy Path
A scenario that describes the expected, successful flow of a feature — what happens when everything goes right and the user stays on the main track.
- SPEC
Scenario
A single plain-language description of how a product behaves in a specific situation. The atomic unit of a Specsight spec.
- SPEC
User Story
A short statement of a feature from the perspective of the user, typically following the format “As a [role], I want to [action], so that [benefit].” A planning artefact, not a behaviour spec.
Specsight operations
How Specsight runs — the unit everything is scoped to, the analyses and syncs that fire on each release, and the integrations they slot into
- OPERATIONS
BYOK (Bring Your Own Key)
A pricing model where you pay a flat platform fee and bring your own API key for the underlying AI provider, paying that provider directly for usage.
- OPERATIONS
Digest
A plain-language summary of what changed in a Project across a chosen time range. Generated on demand or on a schedule, exportable as PDF, and shareable with a link — designed to keep the whole company in the loop.
- OPERATIONS
Full Analysis
The initial scan of an entire codebase that produces the first version of a Specsight spec. From then on, only Syncs are needed.
- OPERATIONS
MCP (Model Context Protocol)
An open standard from Anthropic for connecting AI assistants to external data and tools. Specsight ships a read-only MCP server so assistants can query a live spec.
- OPERATIONS
Project
A connected codebase in Specsight, scoped to one Organisation. Every Feature, Scenario, and changelog entry belongs to exactly one Project.
- 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.
Industry context
The methodologies that came before Specsight — what they got right, what they left unsolved, and where the next step picks up
- INDUSTRY
Behaviour-Driven Development
A software development practice where behaviour is described in a structured format (typically Gherkin) that can be read by stakeholders and executed as automated tests.
- INDUSTRY
Doc-as-Code
A documentation philosophy that treats docs the same way as code: stored in version control, written in plain text, reviewed in pull requests, deployed via CI. Specsight is a different thing: product observability, not docs you write at all.
- INDUSTRY
Gherkin
A structured syntax for describing software behaviour, centred on Given-When-Then clauses. Designed to map directly to automated test steps.
Problems Specsight solves
The failure modes a static documentation system runs into, and the structural reasons they keep coming back
- PROBLEM
Documentation Debt
The accumulated cost of outdated, missing, or unreliable documentation. Like technical debt, but for the gap between how your product behaves and what your team can describe.
- PROBLEM
Documentation Drift
The gradual divergence between written documentation and the product it describes — widens with every release that nobody remembers to document.