There is a persistent tension in how product behaviour gets documented.
On one side: free-form prose. "The user can manage their account settings." Clear enough to write, useless enough to generate follow-up questions forever. What settings? Under what conditions? What happens if the email is already taken?
On the other side: Gherkin — the Given-When-Then syntax from Behaviour-Driven Development. Precise, structured, unambiguous, and deeply alienating to anyone who did not learn it in the context of software testing. Most PMs find it uncomfortable to read. Most customer success managers have never encountered it.
Most product documentation lives in the gap between these two extremes, and struggles.
Context/Action/Outcome sits in the middle: structured enough to be unambiguous, plain enough that any team member can read it without explanation. This post explains what it is, why it is better than the alternatives, and how it makes a living product specification actually work in practice.
The three elements
Every scenario has exactly three parts.
Context is the starting state — who the user is, what condition they are in, what has already happened. Not a user type ("an authenticated user") but a specific situation ("a user whose trial period has expired"). The same user type can be in many states, each producing different behaviour. Context makes that precise.
Action is the trigger — what the user does or what the system does next. Expressed in active terms at the right level of abstraction: specific enough to be unambiguous, not so technical that it requires reading code to understand. "They attempt to upload a file larger than 25 MB" is right. "The multipart form submission exceeds the configured payload limit" is not.
Outcome is what the product does in response. Not what was intended — what actually happens. What is shown, stored, sent, or blocked. Specific enough that someone could verify it by using the product.
Put together, a complete scenario reads as a coherent statement of behaviour:
Context: A user's trial period has expired Action: They attempt to access a premium feature Outcome: They are shown an upgrade prompt and cannot access the feature
Anyone on the team can read that. It can be verified by testing the product. It can be shared with a stakeholder without explanation. Compare it to "users on expired trials are blocked from premium features" — technically the same information, but missing the specificity that makes it actionable and trustworthy.
The three categories
Scenarios are grouped into three categories: happy path (the expected, successful flow), edge case (unusual but valid situations — where most support tickets originate), and error (what happens when things go wrong).
Happy path scenarios are the ones that get written. But a spec that only covers the happy path leaves your support team unprepared for everything else. Edge cases and errors are the scenarios that matter most when customers run into problems — and they are the ones most consistently missing from traditional documentation.
Together, the three categories give a complete picture of a feature's behaviour, not just the ideal flow.
How it compares
Free-text prose is easy to write and easy to write vaguely. "Users can filter their results" tells you a capability exists, nothing about how it works or what happens in edge cases. The format also degrades under updates — there is no structure to anchor changes against.
User stories ("As a [user type], I want to [goal]...") are planning tools. They express intent and rationale. They are not designed to describe what a feature actually does after it ships, and they have no answer for edge cases or error states.
Given-When-Then is structurally similar to Context/Action/Outcome — three clauses, a situation, a trigger, a result. But it is written by engineers for automated test suites. The syntax is machine-parseable, designed to map to step definitions in code.
Given-When-Then is for test runners. Context/Action/Outcome is for your team.
This is not a trivial distinction. Only 3% of engineers completely trust their internal documentation (Port.io, 2025), and developer-facing formats like Gherkin are part of the reason non-engineering teams cannot rely on them. Context/Action/Outcome uses the same underlying structure with no technical syntax, no pipeline integration required, and no assumption that the reader knows what BDD is.
Why the format matters for a living spec
The format is not incidental to how Specsight keeps the spec current. When a release changes how one edge case is handled, only that scenario needs to be updated — the rest of the spec stays accurate. Discrete, structured scenarios make surgical updates possible in a way that prose cannot. A wall of text has no natural update boundary; a scenario does.
This is also why the format works for a wide audience. A PM wants a clear record of what shipped. A customer success manager needs to answer questions confidently. An engineering manager needs to onboard new team members. Free-form prose cannot serve all of these people consistently. Context/Action/Outcome can, because it is structured enough to be precise and plain enough to need no translation.
See the format in practice in the Specsight demo — real features, real scenarios, grouped by category, with changelog. No account required. Ready to connect your own repository? Get started free.
