Vocabulary, defined
Definitions of the words Specsight uses to describe a living product specification — scenario, feature, format, drift, and the methodologies they replace
Table of contents
Concepts
The foundational ideas a living product specification rests on — what it is, what it produces, and the principles behind it
- CONCEPT
Living Documentation
Documentation that is structurally incapable of falling out of sync with the product, because it is derived from the code rather than written separately.
- 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, every Feature carries its own.
- 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 what the product does 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 living product specification.
- SPEC
Feature Graph
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 living product specification.
- 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 stays in sync with your code — the unit we scope to, the runs that fire on each merge, and the integrations they slot into
- OPERATION
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.
- OPERATION
Full Analysis
The initial scan of an entire codebase that produces the first version of a Specsight spec. From then on, only Release Syncs are needed.
- OPERATION
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.
- OPERATION
Project
A connected codebase in Specsight, scoped to one Organisation. Every Feature, Scenario, and changelog entry belongs to exactly one Project.
- OPERATION
Release Sync
The release-triggered update that keeps a Specsight spec in sync with the codebase. Fires automatically every time code lands on the tracked branch.
- OPERATION
Report
A plain-language summary of what changed in a Project across a chosen time range. Generated on demand and exportable as PDF — designed to forward to stakeholders without editing.
Industry context
The methodologies that came before Specsight — what we borrow, what we leave behind, 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 goes one step further and derives docs from code itself.
- INDUSTRY
Gherkin
A structured syntax for describing software behaviour, centred on Given-When-Then clauses. Designed to map directly to automated test steps.
Problems we solve
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 what your product does 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.