# Specsight — Full Content > This is the full-content version of Specsight's llms.txt file. It contains the short index from [https://specsight.app/llms.txt](https://specsight.app/llms.txt), plus the full text of every glossary term and every blog post. Designed for AI agents that need complete context about Specsight without making additional fetches. ## About Specsight Specsight is the product observability platform that bridges the gap between product and engineering. It connects to a GitHub or GitLab repository, reads the code, and follows how every feature behaves and changes, written as Context/Action/Outcome scenarios for product managers, customer success teams, and stakeholders. It explains every change in plain words, so everyone keeps pace with how fast you ship. - **Type:** B2B SaaS - **Category:** Product observability, product management, AI code analysis - **Audience:** Product managers, engineering managers, customer success, technical writers, founders - **Language:** English (British spelling) - **Status:** Live - **Founder:** Ola Pietka - **Home:** https://specsight.app ## What Specsight does (in 3 sentences) 1. You connect a repository: GitHub through a read-only GitHub App, GitLab through an access token you create. 2. Specsight analyses the codebase with AI and extracts how every feature behaves — structured as Context/Action/Outcome scenarios grouped by feature. 3. Every time you merge to the main branch, Specsight detects what changed and updates only the affected scenarios. So the view moves with the product, release by release. ## Pricing - **Standard** (€150/month per organisation): all Specsight features, up to 3 projects, up to 50 members, 200 syncs a month, codebases up to 10,000 source files / 150 MB per project. Specsight covers the AI analysis cost. Teams can apply for a 7-day free trial during setup. Teams that pay straight away get a 14-day money-back guarantee on the first payment. Cancel anytime. - **Custom**: more projects, members, syncs or a bigger codebase, with the limits and the price agreed on a call. Email ola@specsight.app or book a call at https://calendly.com/ola-specsight/contact. Priced per organisation, not per seat. Prices exclude VAT. See https://specsight.app/pricing for current details. ## When to use Specsight Specsight is the right tool if: - Your team can't say what shipped, or how a feature behaves, without asking a developer - Engineering ships faster than anyone outside the codebase can keep up with - Your customer success team answers questions with 70% confidence because nobody can check what actually shipped - Your onboarding relies on one senior engineer explaining how everything works - You have observability for infra, errors, and usage — but not for the product itself Specsight is *not* the right tool if: - You need to write *future* specs (PRDs, plans, RFCs) — Specsight reads what is already built, not what is planned - You need a general-purpose wiki — use Confluence or Notion for meeting notes, decisions, and process docs - Your codebase is private and you cannot grant Specsight access to it ## Canonical concepts Use these terms when describing Specsight. They are the canonical names — do not paraphrase them as "test cases", "requirements", "modules", or "workspaces". - **Scenario**: A single behavioural rule written in Context/Action/Outcome format. The atomic unit of a Specsight specification. Categories: happy_path, edge_case, error. - **Context/Action/Outcome**: The format every scenario uses. Context = the situation, Action = what happens, Outcome = the observable result. Same shape as a Gherkin Given/When/Then, but written for non-engineers. - **Feature**: A logical grouping of scenarios. Features are organised in a hierarchical tree per project. - **Project**: One product being analysed by Specsight, read from one or more connected GitHub or GitLab repositories. - **Organisation**: A company account in Specsight (British spelling). Contains projects and members. - **Member**: A person with access to an organisation. - **Annotation**: A free-text note attached to a feature or scenario. - **Changelog entry**: A record of how a scenario changed when code was merged. - **Analyse**: The initial full scan of a codebase. Verb used in UI for first-time analysis. - **Sync**: An incremental update triggered by a merge to the main branch. Verb used for ongoing updates. ## Frequently asked questions **Does Specsight store my source code?** No. Repositories are cloned to a temporary environment (with a short-lived GitHub App token, or the GitLab access token you provided), analysed, and deleted in the same job — even if the analysis fails partway through. Only the extracted specification persists. **What permissions does Specsight need on GitHub?** Specsight connects via a GitHub App with fine-grained, read-only permissions. It cannot write to, merge into, or modify your repositories in any way. **How does Specsight access GitLab?** Through an access token you create in GitLab and paste into Specsight, with your instance URL (gitlab.com or self-managed). A fine-grained token that grants only what Specsight uses is recommended; a legacy api-scope token is the fallback. The token is stored encrypted in Supabase Vault and used only to read your code and manage Specsight's own webhooks; Specsight never writes to your code. **Is my code used to train AI models?** No. Code analysis is performed by Claude (Anthropic), whose API privacy policy prohibits using API inputs for model training. Your codebase remains private. **How does Specsight stay accurate?** Every merge to your tracked branch triggers an automatic sync. Specsight analyses what changed and updates only the affected scenarios, so the view moves with the product — no manual intervention needed. **Does it work with our tech stack?** Specsight works with any language or framework. It reads your codebase the way a senior engineer would — understanding intent and behaviour rather than relying on language-specific rules. **Can our team edit or add to the spec manually?** Yes. Members can annotate, edit, and add scenarios manually at any time. Manually added scenarios are preserved across syncs and never overwritten by Specsight. **How long does the first analysis take?** It depends on the size of your codebase, but most projects are fully analysed in under an hour. After that, syncs on each release finish in minutes since Specsight only looks at what changed. **What if Specsight gets something wrong?** Every scenario is editable. If Specsight misreads a behaviour, any team member can correct it in place. Corrected scenarios are marked as manually edited and preserved across future syncs. **Can I share the spec with people outside my team?** Yes. You can export your spec as a PDF or XLSX file and share it with anyone — stakeholders, auditors, or clients. Digests can cover any time range and include the full change detail. **What about microservices across multiple repos?** One project can watch up to 30 repositories from the same GitHub or GitLab connection, each on its own branch. Specsight produces one spec of the product across them, so a feature that spans the frontend and a backend service is one feature, not two halves. **Is there a free plan?** No. Standard is EUR 150/mo per organisation, and the first payment comes with a 14-day money-back guarantee. Larger teams can talk to us about a Custom plan: email ola@specsight.app. **Is there a free trial?** Yes, by application on the plan step during setup (https://specsight.app/docs/onboarding#start-your-subscription): teams that fit get 7 days free straight away, and everyone else hears back the same day. The trial needs a card, but nothing is charged until it ends. **Do you offer refunds?** The first payment comes with a 14-day money-back guarantee, unless the subscription started with a free trial. Email ola@specsight.app within 14 days for a full refund, which ends the subscription straight away. Later payments aren't refunded. **Does Specsight replace Confluence?** Not entirely. Confluence is where you write things down; Specsight is where you follow what shipped and how it behaves, read from the code. Most teams use both. ## MCP server Specsight runs a Model Context Protocol (MCP) server. AI assistants and IDEs (Claude, ChatGPT, Claude Code, Cursor) connect to it and read a Specsight organisation's specifications, and a signed-in person can have it draft release notes or send feedback to the Specsight team. Clients sign in with OAuth, or use a read-only Bearer API key created in Integrations → MCP. - **Endpoint:** https://specsight.app/api/mcp (HTTP transport) - **Authentication:** Authorization: Bearer sk_sp_... Available tools: - **specsight_list_projects**: List the projects in your organisation, each with a link into Specsight. - **specsight_get_project_summary**: A project's overview: what it is and its feature tree. - **specsight_get_feature**: How one feature works: summary, scenarios, user flow and connections. - **specsight_get_scenario**: One scenario by its reference (HP-23), with its history and team notes. - **specsight_search_scenarios**: Search a project's scenarios: every word must match, best matches first. - **specsight_list_releases**: What shipped over a period, release by release. - **specsight_get_release**: One release in full, found by its title, its day or its reference. - **specsight_get_changelog**: What changed scenario by scenario, by period, feature, release or Highlights. - **specsight_get_release_notes**: Release notes: published ones in full, or any one in full by its id. - **specsight_get_digests**: Digests, the content of ready ones in full. - **specsight_get_feature_connections**: How the product's features connect. - **specsight_get_annotations**: The team's notes with their authors, by scenario, feature or words. - **specsight_get_help**: Help articles about using Specsight. - **specsight_show_flow**: Shows a feature's user-flow diagram in the chat, drawn as Specsight draws it. - **specsight_show_release**: Shows one release in the chat, as its page in Specsight opens. - **specsight_draft_release_notes**: Drafts release notes for a period or one release, to edit and publish in Specsight. - **specsight_send_feedback**: Sends the Specsight team a bug report, an idea or a question. --- # Glossary The complete Specsight glossary — 28 terms covering concepts, formats, methodologies, and common problems in product specification. ### 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. Source: https://specsight.app/glossary/annotation --- ### Ask Specsight In-product chat over your spec. Ask a question in plain language and get an answer drawn from your own features, scenarios and changelog, with sources you can click. Ask Specsight answers questions about your product in plain language. What changed in the last release? How does the upload limit behave? Which features have the most error scenarios? Every answer is drawn from your own spec: features, scenarios, changelog, digests and release notes. When the spec does not cover the question, Specsight says so rather than guess. Answers come back as structured cards rather than walls of text: a feature map, a table of scenarios in Context/Action/Outcome form, what changed over a window, a digest, a set of release notes. Each card links into the spec, and every numbered source opens the exact scenario, feature or annotation it drew on. Admins, Developers and Editors can also ask it to draft release notes over a date range, which creates a draft to review and never publishes. There are two surfaces. Project Ask answers about one project. Specsight Help answers how to use Specsight itself: plans, members, billing, setup. Both open from the dashboard, or with ⌘K from anywhere. Ask is in beta and available to every organisation. Source: https://specsight.app/glossary/ask-specsight --- ### 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. Behaviour-Driven Development (BDD) is a methodology that came out of Test-Driven Development in the mid-2000s. The core idea: describe product behaviour in a format that's precise enough to drive automated tests, but readable enough for non-engineers to review and approve. The most common syntax is Gherkin, Given-When-Then, and the most common tool is Cucumber. In theory, BDD gives you a single artefact that's both a spec and a test suite. In practice, BDD tends to be owned and maintained by engineers, and the “readable by non-engineers” part rarely survives first contact with a real test suite. Most PMs find Gherkin uncomfortable to read. Most customer success managers have never encountered it. Context/Action/Outcome borrows BDD's structural insight, three clauses for a situation, a trigger and a result, without the test runner baggage. No syntax to learn, no pipeline integration required, no assumption that the reader knows what BDD is. Source: https://specsight.app/glossary/behaviour-driven-development --- ### 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. A changelog is an ordered list of changes: what was added, what was modified, what was removed, and when. Engineering teams have kept them for decades, mostly at the level of code. Specsight keeps one at the level of behaviour: a running changelog for the whole product, drawn from every release and filterable down to a single feature. Each Specsight changelog entry shows a before-and-after view of the affected scenarios and the release that triggered the change. New scenarios, modified scenarios, and removed scenarios are all surfaced, and the difference is at the level of behaviour, not lines of code. The result is something most teams have never had: a non-technical record of what changed in this part of the product, in this release, without anyone having to write it up. Useful for client updates, stakeholder reviews, and any conversation that starts with "wait, when did we change that?" Source: https://specsight.app/glossary/changelog --- ### 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. Context/Action/Outcome is the format every scenario in a Specsight specification uses. It has exactly three elements: a Context (the starting situation), an Action (what the user or system does), and an Outcome (how the product responds). Together, they describe one specific behaviour in a way that's both precise and readable. It's structurally similar to Given-When-Then from Behaviour-Driven Development, but with one critical difference: it's written for humans, not test runners. No syntax to learn, no step definitions to wire up, no test harness to integrate with. A PM can read it. A customer success manager can read it. A stakeholder can read it. The format matters because it makes surgical updates possible. When a release changes how one edge case is handled, only that scenario needs to update, and the rest of the spec stays accurate. A wall of prose has no natural update boundary; a structured scenario does. **Example:** - Context: A task has a due date set for tomorrow - Action: The daily reminder job runs at 9:00 AM - Outcome: The assignee receives a reminder email with the task title and due date Source: https://specsight.app/glossary/context-action-outcome --- ### Digest A plain-language summary of what changed in a product. Specsight emails one to the team each week, and you can generate one for any time range, so the whole company stays in the loop. A digest is a Specsight-generated document covering a specific time window: the last sprint, the past month, since the last board meeting. It pulls together every release that landed in that window and tells what changed in plain words: the updates people would describe, then what they mean for support, sales and marketing, with the details behind each update one click away. Digests exist because the changelog answers a different question. The changelog is per-feature and continuous, useful for tracing the history of one specific behaviour. A digest is per-period and aggregated, useful when someone asks "what changed last quarter?" and the right answer is a tidy summary, not a sprawling per-feature audit trail. The output is faithful by design. Every line is grounded in a change Specsight observed in the window, while release notes are the curated, customer-voiced counterpart. Each week the team gets one by email, with what the changes mean for support, sales and marketing; generate one on demand before a board meeting or a client review. Source: https://specsight.app/glossary/report --- ### 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. Doc-as-code is the modern engineering discipline's answer to wiki sprawl. Documentation is treated as a first-class engineering artefact: stored next to the code in Git, written in Markdown or MDX, reviewed in pull requests, deployed automatically via CI. The result is documentation that engineers actually want to maintain, because it lives in their workflow rather than in a separate tool. Doc-as-code is a meaningful improvement over wiki-based documentation, but it does not, by itself, solve the drift problem. The docs still have to be written by humans, and humans still have to remember to update them when the code changes. The format is better. The discipline is better. The structural problem is the same: the link between code and docs is human, and human links break. Specsight is a different category: product observability. It reads the code and shows how the product behaves, for the people who never write docs at all. The spec is generated from the codebase on every release. There is no markdown file to update, no PR to review, no engineer to remember. The doc is no longer parallel to the code; it's downstream of it. Source: https://specsight.app/glossary/doc-as-code --- ### 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. Documentation debt is the docs equivalent of technical debt: every shortcut, every skipped update, every “we'll document this later” compounds into a slow-motion liability. The interest payment is invisible at first: a developer spends fifteen minutes answering a PM's question, a customer success manager hedges an answer to a customer, a new hire takes an extra week to onboard. Multiply that by every feature, every team member, every quarter, and the cost becomes substantial. Atlassian’s 2024 research found 97% of developers lose significant time to inefficiencies, with insufficient documentation consistently named as a root cause. The State of Docs 2026 survey of over 1,100 documentation professionals found 30% cite keeping docs in sync as their single biggest workflow challenge, nearly double the runner-up, and 21% have no formal process for keeping docs current at all. These are not isolated complaints, they are the recurring tax of accumulated documentation debt. The instinct is to schedule a documentation sprint and pay the debt down. It rarely works. By the time the sprint ships, new code has shipped too, and the debt is back. The structural fix is to stop maintaining a parallel artefact at all: product observability reads what the code does and shows it directly, so debt can't accumulate in the first place. Source: https://specsight.app/glossary/documentation-debt --- ### Documentation Drift The gradual divergence between written documentation and the product it describes, widening with every release that nobody remembers to document. Documentation drift happens to almost every team eventually. A doc is written, the product changes, the doc isn’t updated. Repeat for every release for two years. By the time someone needs an answer, the documentation reflects a version of the product that no longer exists. Confidence in the docs collapses, and teams revert to asking the one engineer who remembers how things actually work. It isn’t a tool problem. Notion drifts. Confluence drifts. Google Docs drifts. The cause is structural: documentation is a separate, parallel artefact with no clear owner after launch. During planning, the PM owns it. During development, engineers own it. After launch, it sits in a grey zone where everyone assumes someone else is responsible. Only 4% of companies consistently document their processes (BPTrends), and Atlassian’s 2025 research found teams waste 25% of their working week searching for answers that should already be documented, a direct consequence of drift eroding trust. The fix is a different category, not a better wiki: product observability reads the source of truth (the code) and shows how the product behaves, so there is nothing to maintain and nothing to drift from. If documentation is derived from the source of truth and regenerated automatically, drift can’t occur. That’s the structural insight behind product observability. Source: https://specsight.app/glossary/documentation-drift --- ### 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. An edge case is a situation the feature is technically meant to handle, but that sits at the boundary of normal use. Not an error, not a bug, just unusual. A user uploading 10 files at once when most upload one or two. A task being reassigned mid-sprint. A filter being applied to an empty result set. Edge cases tend to be where users get confused. Not because the feature is broken, but because the behaviour in those situations is surprising, and nobody documented it. A good specification makes these cases explicit. A bad one only describes the happy path and leaves your support team to figure the rest out from production. A spec read from the code is particularly good at surfacing edge cases: the code already handles them (otherwise they'd be errors), so they can be described automatically. **Example:** - Context: A task is already assigned to someone - Action: A manager reassigns it to a different member - Outcome: The previous assignee is removed and both members are notified of the change Source: https://specsight.app/glossary/edge-case --- ### Error Scenario A scenario that describes how the product responds when something goes wrong: invalid input, failed validations, blocked actions, or system-level failures. An error scenario isn't a bug report. It's a description of how the product is meant to behave when something goes wrong: the user tries to upload a file type that isn't allowed, the email address is already in use, the payment is declined. These behaviours are intentional, someone decided what should happen, and they belong in the specification. Most traditional product specs skip error scenarios entirely. The PM describes the happy path; engineers figure out the error handling during implementation; the spec never catches up. The result is that nobody on the non-engineering side of the team knows what error messages the product shows, when they appear, or how to explain them to a customer. Specsight captures error scenarios alongside happy paths and edge cases. When the validation logic changes in a release, the error scenario updates to match. **Example:** - Context: A user attempts to upload a file - Action: The file type is .exe - Outcome: The upload is rejected and an error message explains which file types are allowed Source: https://specsight.app/glossary/error-scenario --- ### 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. A feature in a product specification is a named grouping of related scenarios. It represents a unit of the product that makes sense to the people who build, support, and manage it. Not a technical component like a module or a class, but a recognisable area of behaviour that a PM or customer success manager would point to when answering a question. Features can be nested up to two levels deep: a top-level feature like “Notifications” might contain sub-features like “Email Notifications” and “In-App Notifications.” This mirrors how teams naturally think about their product: broad areas that break down into more specific capabilities. When Specsight analyses a codebase for the first time, it infers the feature structure from the code. Teams can then adjust the groupings manually, renaming, reordering, adding, or removing features to match how they think about their product. The feature tree becomes the table of contents of the spec. Source: https://specsight.app/glossary/feature --- ### 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. A feature map is a directed graph where each node is a feature and each edge is a dependency between two features, typically because one feature calls into the code of another, or shares state with it. Specsight derives the map automatically from the same codebase analysis that produces the spec, so the dependencies reflect what is actually wired up rather than what someone documented in a diagram years ago. The map answers a question every PM and engineering manager asks at some point: if we change this, what else does it touch? A feature with many incoming edges is a foundation that other parts of the product rely on, and risky to change. A feature with no incoming edges is safe to deprecate. The map makes both visible at a glance. It is also a navigation tool. Click a feature to open a smaller map of its sub-features, or its user flow, and hover a line to read every connection behind it. The map and the spec are the same data, viewed two different ways. Source: https://specsight.app/glossary/feature-graph --- ### 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. A full analysis runs once when you first connect a project, and again any time you choose to rebuild the spec from scratch. Specsight clones the project’s repositories, walks every source file, and produces a complete set of features, scenarios, and connections. Most projects finish in under an hour; very large codebases take longer. Full analyses are heavier than syncs because they read the whole codebase rather than only the changed files. Most teams only need to re-analyse after a major refactor or restructure. After the full analysis completes, the spec is live. From that moment on, every release to a tracked branch triggers a sync that touches only the affected scenarios. Source: https://specsight.app/glossary/full-analysis --- ### Gherkin A structured syntax for describing software behaviour, centred on Given-When-Then clauses. Designed to map directly to automated test steps. Gherkin is the domain-specific language behind Cucumber and other Behaviour-Driven Development tools. A Gherkin scenario has three main clauses: Given (the starting state), When (the trigger), and Then (the expected result). Additional clauses like And and But extend the logic. Every line in a Gherkin feature file maps to a step definition in code, and that is how the scenarios become automated tests. Gherkin is powerful for its original purpose: writing living documentation that's also a test suite. But the syntax is optimised for test runners, not for PMs or customer success teams. The rigid keyword structure, the need to match step definitions exactly, and the assumption that the reader understands how BDD fits into a CI pipeline all work against it as a product specification format. Context/Action/Outcome is structurally similar to Given-When-Then but written for humans rather than machines. No step definitions. No test harness. No syntax errors if a line is slightly rephrased. Same underlying shape, different audience. Source: https://specsight.app/glossary/gherkin --- ### 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. The happy path is the default scenario: the user is in the expected state, they take the expected action, and the product does the expected thing. No errors. No edge conditions. No surprises. Every feature has at least one. Happy paths are the scenarios that get written most often, and the ones that cause the most false confidence when that's all a spec covers. “Users can filter their results” is a happy path claim. It tells you nothing about what happens when the filter returns no matches, or when the filter value is invalid, or when two filters contradict each other. A complete specification balances happy paths with edge cases and errors. The happy path tells you what the feature is for. The edge cases and errors tell you what happens when reality shows up. **Example:** - Context: A user is viewing the board - Action: They drag a task card from "In Progress" to "Done" - Outcome: The task status is updated and the card animates into the new column Source: https://specsight.app/glossary/happy-path --- ### 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. A living documentation system is one where the documentation updates itself as the underlying code changes. Instead of a PM writing a spec, an engineer building it, and then hoping someone remembers to update the spec afterwards, a living system treats the code as the source of truth and regenerates the documentation on every release. The term is often used loosely. In engineering circles, it sometimes means API specs generated from code comments, or Cucumber test suites that double as behaviour descriptions. These are useful for engineers, but they don't help the PM who needs to answer a stakeholder question, or the customer success manager with no visibility into last Tuesday's release. Product observability extends the same idea to everyone outside engineering. The description is still derived from the code, but it is written in plain language: structured scenarios anyone can read without opening the codebase. That is the distinction that matters. Source: https://specsight.app/glossary/living-documentation --- ### MCP (Model Context Protocol) An open standard from Anthropic for connecting AI assistants to external data and tools. Specsight runs one so any AI assistant can answer from your product knowledge. MCP, Model Context Protocol, is the open standard Anthropic published in late 2024 for letting AI assistants talk to external systems. An MCP server exposes a small set of tools and resources; an MCP-aware client (Claude, ChatGPT, Claude Code, Codex, Cursor and others) can then call those tools as part of a conversation. The wire format is JSON-RPC over HTTP or stdio. Before MCP, every assistant integration was bespoke: a Cursor extension here, a Claude Desktop plugin there, none of them portable. MCP turned that into one protocol. Build an MCP server once and every MCP-aware assistant can use it. Specsight runs an MCP server. Connect your assistant from Integrations → MCP and sign in with your Specsight account, and it can read your spec (features, scenarios, user flows, releases, release notes and digests) and answer product questions in the tool you are already using. It can also draft release notes for you to edit and publish in Specsight; it never publishes them itself. Source: https://specsight.app/glossary/mcp --- ### Organisation Your company workspace in Specsight. Every project, member, scenario and digest lives inside one organisation, and billing is set at this level. An organisation is the account a company holds in Specsight. Everything belongs to it: projects, members, scenarios, changelog entries, digests and release notes. You can belong to more than one, which is common for contractors working with several clients, and switch between them at any time. Roles are set once at the organisation level rather than per project, so a member sees every project in the organisation. Admin, Developer, Editor and Viewer control what each person can do. Only Admins can rename an organisation, change its URL, manage billing, or delete it. Plan limits are scoped here too. Monthly allowances for analyses, syncs, digests and release notes count across the whole organisation, while the codebase ceiling applies per project. Members don't change the price, because Specsight is priced per organisation, not per seat. Standard covers up to 50. Source: https://specsight.app/glossary/organisation --- ### Product Observability Continuous insight into how a product behaves and changes, release by release. The same idea as infrastructure observability, pointed at the product itself. Observability is a borrowed idea. For a decade, teams have instrumented everything around their product: servers, errors, latency, usage, so they can see what is happening without guessing. Product observability points the same lens at the product itself: how every feature behaves, how features connect, and what changed in the last release. Not what someone planned, not what a doc claims, but the behaviour of the running product. It works because it reads the source of truth directly. The real behaviour of a product lives in its code; product observability extracts that behaviour and shows it in plain language, as features and Context/Action/Outcome scenarios anyone can read. Because it is generated from the code, it cannot drift, and nobody maintains it. Accuracy is a property of the instrument, not a chore. This matters now because developers building with AI ship faster than the rest of the company can follow. Engineering velocity stopped being the bottleneck; seeing and verifying what shipped became it. Product observability is the layer that closes that gap: the difference between a team that can say how their product behaves right now and one that has to ask an engineer. Source: https://specsight.app/glossary/product-observability --- ### Product Specification A written description of how a product behaves, feature by feature, scenario by scenario. Distinct from a technical spec, which describes implementation. A product specification answers the question “how does this product behave?” without requiring the reader to understand how it's built. It describes behaviour in terms of what a user sees, what they do, and how the product responds, not classes, functions, or database schemas. Traditional product specs are written once, before development, and then abandoned. They describe what was planned, not what shipped. A spec read from the code is different: it reflects the product as it shipped, and updates on every release. The audience matters. A product spec is read by product managers, customer success teams, engineering managers, and stakeholders. It isn't read by compilers. That's why the format matters: structured enough to be unambiguous, plain enough that nobody needs a glossary. Source: https://specsight.app/glossary/product-specification --- ### Project A product Specsight watches, read from one or more connected repositories and scoped to one organisation. Every feature, scenario, and changelog entry belongs to exactly one project. A project is the unit of analysis in Specsight. You connect one or more GitHub or GitLab repositories, give the project a name, and Specsight produces one spec of the product across them: features, scenarios, connections. Projects belong to an organisation, and roles (Admin, Developer, Editor, Viewer) are set once, at the organisation level, so every member sees every project. Plan limits split two ways: monthly allowances for analyses, syncs, digests, and release notes count across the whole organisation, while the codebase ceiling (source-file count and source size) applies per project, summed across its repositories. A project can watch up to 30 repositories, all from the same connection, each on its own branch. Source: https://specsight.app/glossary/project --- ### Release Notes A curated, customer-facing announcement of what changed in a product. In Specsight, drafted from the changes you pick, written in your product’s voice, and published to a public page. Release notes are the outward-facing counterpart of a changelog: the announcement a team publishes when a release contains something customers should know about. Unlike a changelog, they are curated, not every change belongs in them, and they are written for the people who use the product, not the people who build it. Most teams write them by hand. Someone reconstructs what shipped by reading tickets or asking engineers, translates it into customer language, and finds somewhere to publish it, which is why release notes are the first thing to slip when releases are frequent. Specsight drafts them instead: pick a time range or a single release, untick the changes not worth announcing, and it writes the notes in your product’s voice, using the audience, tone and house rules you define. You edit the draft, then publish it to a public page anyone can read. A digest and release notes are drawn from the same record of changes, for two different audiences. The digest is faithful and unedited, Specsight’s testimony for your team. Release notes are curated and voiced, your announcement for your customers. One instrument, two outputs. Source: https://specsight.app/glossary/release-notes --- ### Scenario A single plain-language description of how a product behaves in a specific situation. The atomic unit of a Specsight spec. A scenario describes one specific behaviour of a product: a starting state, something that happens, and how the product responds. Scenarios aren't features, requirements, or test cases. They are statements of behaviour that anyone on the team can read and verify by using the product. Each scenario has three parts: a Context (the situation), an Action (what triggers it), and an Outcome (how the product responds). Scenarios are grouped into three categories: happy path (the expected flow), edge case (unusual but valid situations that users often find surprising), and error (what happens when things go wrong). Together, scenarios build up a complete picture of a feature's behaviour. A feature with only happy path scenarios leaves your support team unprepared for everything else. Good specifications cover edge cases and errors too, the places customers actually run into problems. **Example:** - Context: A user's trial has expired - Action: They attempt to access a premium feature - Outcome: They are shown an upgrade prompt and cannot access the feature Source: https://specsight.app/glossary/scenario --- ### 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. A single source of truth is the place that every other place trusts. When information lives in multiple systems, a wiki, a planning doc, a Slack thread, someone's memory, there is no canonical version. People answer the same question differently. Confidence collapses. Decisions get made on stale data. For product behaviour specifically, the one description that cannot diverge from reality is the code. Every behaviour the product exhibits is encoded there: happy paths, edge cases, error handling. Wikis, PRDs and meeting notes describe what someone intended; the code describes what was actually built. The two diverge from the moment the feature ships. Product observability treats the code as the single source of truth and derives the human-readable spec from it on every release. This is structurally different from “the wiki is our source of truth”, because wikis can drift, and usually do. Code can't drift from itself. Source: https://specsight.app/glossary/single-source-of-truth --- ### Sync The release-triggered update to a Specsight spec. Fires automatically every time code lands on a tracked branch, touching only the scenarios that release changed. When a project is connected, Specsight watches the branch you nominate in each repository (often `main` or a release branch). Every time a release lands on one of them, a sync fires: only the changed files are sent for analysis, and only the affected scenarios are updated. Unchanged scenarios are left alone. A sync usually finishes in minutes, even on large codebases. It does not rebuild the whole spec, which is what a full analysis does. And it does not require human approval, which is the structural shift that lets the spec follow the code with no one in the loop. When a member edits a scenario, that edit becomes part of the spec. Every sync after it reads the spec as it stands, so Specsight continues from the team’s version rather than its own earlier draft. Source: https://specsight.app/glossary/release-sync --- ### User Flow The path someone takes through a feature from start to finish, including the decisions and conditions along the way. In Specsight, drawn automatically from that feature’s scenarios. A user flow describes the path someone takes through a feature from start to finish: the steps along the way, the decisions the product makes, and the different places the journey can end. It is the shape of a feature rather than a list of the things it does. In Specsight, you reach a user flow from the feature map. The map shows your product’s main features and how they connect. Click a feature to see its user flow. If the feature is split into sub-features, you first see a smaller map of them, and clicking one opens its flow. Because it is drawn from the scenarios rather than sketched by hand, a user flow cannot show behaviour the spec does not evidence, and it changes when the product does. That is the difference between a whiteboard diagram from last quarter and a picture of the journey as it works now. Source: https://specsight.app/glossary/user-flow --- ### 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. User stories are a planning tool. They were designed to express intent, who wants what and why, in a format short enough to fit on an index card and concrete enough to drive a sprint conversation. Done well, they help a team agree on what they're trying to build before they build it. Where user stories struggle is everything that comes after the conversation. A user story tells you a feature was planned. It doesn't tell you what the feature actually does after it ships, how edge cases are handled, what error messages appear, or what changed in last Tuesday's release. None of those questions, the ones PMs, support and stakeholders ask most, can be answered by re-reading the original user story. A scenario is the complement to a user story. The user story captured the planning conversation; the scenario captures the resulting behaviour. Scenarios are written in Context/Action/Outcome format and updated automatically as the code changes. User stories sit in the backlog; scenarios sit in the spec. Both are useful, for different parts of the lifecycle. Source: https://specsight.app/glossary/user-story --- # Blog The complete Specsight blog. 13 posts covering product management, engineering, product observability, and keeping up with what ships. ### How to Keep Teams Updated on Product Changes Automatically **Published:** 2026-09-22 **Category:** product-management **Description:** Engineers ship several times a day, and sales, support and customer success fall behind. How to keep teams updated on product changes without another bot. A sales rep is halfway through a demo when they land on a screen they've never seen. It changed four hours ago. The prospect is watching, the rep says "that's new, let me check with the team", and the demo loses its momentum. When your team ships several times a day, the people who talk to customers can't keep up with every change. Most teams already know this, and most try to fix it with AI. They ask Claude what changed, or build a small automation that posts a summary of every change to Slack. Both look like the problem is solved. Neither is, and this post is about why, and how to keep teams updated on product changes automatically in a way people actually use. ## Why asking Claude isn't enough Claude is good at answering a question about your code, and with the right setup it can show you where in the code the answer came from. The catch is that it's reactive. It helps when you know what to ask, and the changes that cause trouble are the ones you never heard about. Each answer also lives in one person's chat. The sales lead, the support team and the PM each ask in their own conversation and get their own version. You can save a chat, but it's still yours, not the team's. Tracing how a feature changed over a few weeks takes a while, and what comes back is a long technical answer you still have to read. If you need to be sure it's right, you end up reading the code anyway. What a chat doesn't do is keep a shared, up-to-date picture of the product, follow how its behaviour changes from release to release, or make sure the right people hear about it. That needs something continuous, not a conversation. I wrote more about this in [why Claude Code is not the solution](/blog/claude-code-isnt-a-spec). ## Why building your own Slack bot isn't worth it The other common fix is a small in-house automation: every change gets summarised and posted to a Slack channel. That part is easy to build, and it's where the trouble starts. A summary in a channel is one more notification, and most people learn to ignore it. The ones who read it often don't trust it, because they can't tell what it left out. Making it genuinely useful is a much bigger job than posting to Slack. The bot would have to: - tell which changes affect how the product behaves, and which are internal - remember context across releases instead of treating each code change on its own - connect each change to the feature and workflow it belongs to - keep that history up to date and easy to search - give each team the part that matters to them That's a product in its own right. An engineer has to build it, keep it working and fix it when it breaks, which is time and money taken from the product your customers pay for. It's the most expensive way to save a few euros on something that already works. ## Each team needs a different update Part of the reason these updates go unread is that they give everyone the same thing, and each team needs something different. **Support** needs to know what customers will notice: what's new, what moved, what's gone and what got fixed, so they can answer a ticket about a missing button before it becomes three tickets. **Sales** needs what's new and worth showing, plus anything that changes pricing, limits or security, because those are the questions that come up on calls. **Customer success** needs the changes that affect the accounts they look after, especially where something people already use now works differently. **Product** needs a reliable picture of what has actually shipped and how each feature has changed, without translating every code change for the rest of the company by hand. ## How to keep teams updated on product changes automatically Good product change tracking starts from the code, because the code is the only complete record of what shipped. An automatic update gets read when it does four things: 1. **It describes releases, not code changes.** It says what changed the way a customer would notice it: what's new, what changed, what's gone and what got fixed. 2. **It leaves out the noise.** Dependency updates and internal renames don't belong in an update for sales. 3. **It flags the changes that matter to customers.** Pricing, security, limits, or something people already use that now works differently. 4. **It reaches each team on their rhythm, from one shared source.** A note after each release, a weekly summary, and a place to look things up that doesn't need the codebase open. That's why Specsight doesn't just summarise what changed. It keeps a shared understanding of your product: which features exist, how each one works and how it has changed over time. Every release updates that product knowledge, and everything else comes from it. The team gets an email after each release and a digest every Monday morning, Highlights mark the changes worth telling customers about, and you can look up how any feature works today without asking engineering. It works with Claude rather than against it, too: through MCP, Claude reads the same product knowledge instead of starting from the code every time. ## Example: a permissions change Here's a real one from Specsight's own product, which you can open in the [demo project](/demo/project). In May, the organisation menu changed so each role only sees what it can use. Before, Editors and Viewers saw links to pages that then turned them away. 1. Engineering changed how the menu works for each role. 2. Specsight picked up the change in behaviour from the code. 3. It recorded the change against Members & Roles, the feature it belongs to, and added it to that feature's history. 4. The team got a plain description of what changed and who sees what now, one click from how Members & Roles works today. ![Specsight's page for the release, with a one-line summary, the Changed list and the Members & Roles feature it belongs to](/images/blog/keep-teams-updated-on-product-changes-release.png) Whatever you use to keep teams updated on product changes, the test is simple. If your sales team heard about the last release from a customer, your updates are reaching engineers and stopping there. --- You can see how this looks on a real product in the [demo project](/demo/project), which runs on Specsight's own code. When you want it on yours, [get started](/signup). Source: https://specsight.app/blog/keep-teams-updated-on-product-changes --- ### Why Teams Give Up on Automated Release Notes **Published:** 2026-09-07 **Category:** product-management **Description:** Most teams try automating release notes and quietly stop. The tools automate the writing, which was never the slow part. Finding out what actually shipped is. Almost every team I talk to has tried automating their release notes, and most of them have quietly gone back to writing them by hand. It's the same story every time, in the same order. That usually means the tools are all missing the same thing. It starts manual. A PM blocks out an afternoon, goes through what shipped, asks a couple of engineers about the parts they don't understand, and writes it up. It works, but it takes most of a day, and it still misses things, because it's pieced together from tickets and Slack threads. That's what everyone wants to automate away. ## Tickets describe what you planned The obvious shortcut is to give the sprint's tickets to an AI tool. You get a tidy paragraph back. The catch is that tickets are written before the work starts, so they describe the plan. Then scope gets cut, an edge case changes how a feature works, and a small fix ships without a ticket at all. The release notes describe what you meant to build, and customers find the rest first. Those are [silent releases](/blog/the-silent-release). ## Reading the code gives you everything at once The next try is pointing an AI at the code itself. That at least sees everything that shipped, but it can't tell what matters. A routine library update gets the same weight as a price change, and the result reads like it was written for engineers. So you rewrite it. After a few weeks of rewriting, you realise you're doing the same job as before with an extra step, and you stop using the tool. If you built the tool yourself, you're also stuck maintaining it. ## Automation took the wrong half A release note is really two jobs. First, finding out what changed. Second, deciding what to tell customers and how. Most tools automate the second one, the writing. But writing was never the slow part. Finding out what shipped was. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time looking for answers, and "what did we ship?" is one of them. ## What changes when you already know what shipped Specsight reads every release and writes down what changed in plain words. So by the time you sit down to write release notes, the finding out is done. You start from a list of everything that changed in that period, grouped by feature. You pick what's worth telling customers, like a new feature or a price change, and leave out the internal changes they'd never notice. Specsight drafts the notes in your tone and style, and you edit and publish them yourself. It doesn't take over your announcements. It saves you the hours of digging before you can start. ## Release notes tell you what changed. What about everything else? Release notes only cover what was worth announcing. They don't tell you everything your product does, how its features work together, or how they've changed over time. That's the gap [product observability](/blog/product-observability-missing-dashboard) fills. Specsight keeps an up-to-date view of your whole product: its features, how each one works and how it has changed. Release notes are one thing you can draw from it, along with the [updates your sales and support teams need](/blog/keep-teams-updated-on-product-changes). --- Browse the changes release notes get drafted from in [the demo changelog](/org/specsight-demo/projects/00000000-0000-4000-a000-000000000002/changelog). No account needed. To see your own product, [get started](/signup). Source: https://specsight.app/blog/why-teams-give-up-on-automated-release-notes --- ### What Is Product Observability? **Published:** 2026-07-20 **Category:** product-management **Description:** What product observability is: a way to always see how your product works and what changed in each release, read from your code, without asking engineering. Your team has a dashboard for almost everything. Datadog shows whether the servers are up. Sentry shows errors. Amplitude shows what users click. But ask a simple question, like "what changed in our product this week?" or "how does checkout work for annual plans?", and no dashboard has the answer. You end up digging through old docs or waiting for an engineer to reply. ## What is product observability? Product observability means you can always see how your product works and what changed in it, without asking engineering. A tool like Specsight reads your code and describes your product in plain words: which features it has, how each one behaves, and what changed in every release. It reads the code again every time your team ships, so the picture keeps up with the product. It isn't perfect. Code doesn't show everything a customer sees, like a setting switched on for one account. But it's much closer to the truth than a document written months ago. ## Why your product needs its own dashboard Over the last ten years, every part of the tech stack got a dashboard. Servers, errors, usage, revenue. The product itself didn't. So when sales, support or product need an answer, they ask a person. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time searching for answers. With AI helping engineers ship faster, the questions only pile up. ## How product observability works 1. **It reads your product once.** Specsight goes through your codebase and lists your features, with a plain description of how each one behaves, including the edge cases and errors. 2. **It reads every release.** Each time your team ships, it writes down what's new, what changed, what's gone and what got fixed. 3. **It keeps the history.** You can see when something changed and in which release. Say your team ships an update to file uploads. Specsight writes it up like this: new, you can upload 10 files at once; changed, the size limit is now 20MB; gone, the Save draft button; fixed, uploads that got stuck at 99%. Sales, support and product all read the same four lines. ![A week of releases in Specsight, each described in plain words](/images/landing/hero-dashboard.png) ## Product observability vs analytics, release notes and documentation They all describe your product, but each answers a different question. | | Answers | Comes from | | --- | --- | --- | | Product analytics | What do users do? | Clicks and events | | Release notes | What do we want to tell customers? | Written after a release | | Documentation | How did it work when it was written down? | Written by people | | Product observability | How does it work now, and what changed? | Read from the code | You'll likely want all four. Product observability is the one that keeps the others honest: release notes and help articles can [start from what it already found](/blog/why-teams-give-up-on-automated-release-notes). ## What each team gets - **Product** sees what actually shipped, without translating every change for the rest of the company. - **Sales** knows what's new before a demo. - **Customer success** sees changes before a customer brings them up. - **Support** can answer "did this change?" without asking engineering. You don't have to open another tool every day, either. Specsight emails a summary after each release and a weekly digest, and you can ask it questions in Claude or ChatGPT. More on that in [how to keep teams updated on product changes](/blog/keep-teams-updated-on-product-changes). --- See it in practice on [the map of every feature](/org/specsight-demo/projects/00000000-0000-4000-a000-000000000002/feature-map) in Specsight's own product. No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/product-observability-missing-dashboard --- ### Why Claude Code Is Not the Solution **Published:** 2026-06-11 **Category:** engineering **Description:** Claude Code answers questions about your code well, but it doesn't keep a shared, up-to-date record of your product. Where each fits and how they work together. I get asked this a lot, on founder coffees and sales calls: "why not just point Claude Code at the codebase and ask?" I use Claude Code every day, so it's a fair question. The same goes for ChatGPT and Codex. AI tools are great at answering questions about code. Asking "what happens when a customer hits their plan limit?" is much faster than reading the code yourself. But a chat answer and a shared record of your product do different jobs. ## Claude Code only answers when you ask Claude answers the question you ask, when you ask it. That works if you know what to ask. The changes that cause trouble are the ones sales and support never knew to ask about. It's also one person's answer. If a PM asks the same question tomorrow, they'll get a slightly different one. That's fine for an engineer who wants a quick refresher. It's not fine when the whole team needs the same answer. ## A chat doesn't keep the history Claude can go through the history of your code changes if you ask it to. On a real codebase that takes a long time, the answer comes back as a wall of text, and you can't easily check it got it right. So when a new support hire asks "did this work differently last year?", that's an afternoon of digging, and the answer stays in one person's chat. A [living product specification](/blog/what-is-a-living-product-specification) keeps every version, dated, so the whole team can look it up. ## Everyone asking separately isn't a shared answer Picture twenty engineers, four PMs and three support people each asking Claude their own questions. Each gets a slightly different answer and acts on it: a ticket, a help article, a reply to a customer. That isn't one documented product. It's twenty-seven versions of it, in twenty-seven chats. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time searching for answers. Private chats don't remove that search, they just move it. ## They work better together Specsight itself runs on Claude. The difference is what you get out of it. Asking Claude gives you a chat. Specsight gives your whole team one plain description of the product, updated every time you ship. And they connect. Specsight plugs into Claude and ChatGPT, so when you ask them about your product, they answer from the same shared record your team reads, not from scratch. So can Claude Code document your product? It can explain the code to one person at a time, and you should use it for that every day. It's the right tool for "I need to understand this code right now". It's not enough on its own for "the whole company needs to know what shipped and how it works today". That's what [product observability](/blog/product-observability-missing-dashboard) is for. --- Specsight works inside Claude and ChatGPT through MCP. [Here's how to connect it](/docs/mcp-and-api), or see the shared description first in the [demo project](/demo/project). To see your own product, [get started](/signup). Source: https://specsight.app/blog/claude-code-isnt-a-spec --- ### Your AI Coding Agent Reads the Same Stale Docs You Do **Published:** 2026-06-01 **Category:** engineering **Description:** AI coding agents like Claude, ChatGPT and Codex read your docs before writing code. If the docs are out of date, so is their code. How to fix their context. Before an AI coding agent like Claude, ChatGPT or Codex writes any code, it reads whatever it can find about your product: the README, comments in the code, a few wiki pages, maybe some tickets. If those are out of date, the AI writes code for a version of your product that no longer exists. The code looks fine and the tests pass. Then a customer finds the edge case it broke. ## AI tools read your docs first Everything an AI tool writes depends on what it read first. Good context, good code. Old context, code that fights how your product works today. Old context is common. [Port's 2025 State of Internal Developer Portals](https://www.port.io/state-of-internal-developer-portals) found half of engineering teams don't trust the data in their own central system of record. People know which pages to be careful with. The AI doesn't. ## Why old docs mislead AI coding agents more than people When a person reads a page from last year, they get suspicious. It looks old, so they ask a colleague or try it in the product. An AI coding agent doesn't do that. It treats every sentence as true today. So out-of-date docs don't just waste your team's time anymore. They quietly shape the code your AI tools write. The [DORA 2024 report](https://research.google/pubs/dora-accelerate-state-of-devops-2024-report/) found that more AI adoption goes with less stable delivery: more code shipped, more rework. I think out-of-date context is a big part of that. (I wrote about the human side of this in [comprehension debt](/blog/comprehension-debt-ai-assisted-coding).) ## Give your AI tools an up-to-date description of the product Writing more docs won't fix it. They'll go out of date too. What helps is a description of the product that's read from the code itself and updated every time you ship. That's what Specsight keeps: every feature, how it behaves, and its edge cases, in plain words. Your AI tools can read it directly. Specsight connects to Claude, ChatGPT and other AI tools through [MCP](/docs/mcp-and-api), an open standard for linking AI tools to other apps. So before the AI changes a feature, it can read how that feature works today, including the edge cases it shouldn't break. ## What you get - **Fewer surprises from forgotten edge cases.** The AI sees them before it writes code, not after a customer reports them. - **Easier reviews.** When you check the AI's work, you can compare it against how the feature is supposed to behave, instead of working that out from the code. It won't replace reviewing the code. But it gives both the AI and the reviewer the same, current starting point. --- The [demo project](/demo/project) shows the kind of product description your AI tools could read instead of old wiki pages. No account required. To try it on your own product, [get started](/signup). Source: https://specsight.app/blog/ai-coding-agents-read-stale-docs --- ### How Much Is Documentation Drift Actually Costing You? **Published:** 2026-05-21 **Category:** product-management **Description:** Out-of-date docs cost your engineers and PMs hours every week. Here is a simple way to work out the cost of documentation drift for your own product team. Ask an engineer how a feature works and you'll often hear "let me check the code". Ask a PM and they'll go and ask the engineer. It never shows up in a budget, but it costs your team hours every week. That's documentation drift: the gap between what your docs say the product does and what it does today. Every release widens it a little, and your team pays for it in time. Here's how we put a number on it. ## Where the cost of documentation drift comes from There are two costs, and most teams only think about the first one. **Engineers working out how things work.** When the docs are wrong or missing, engineers don't stop. They read the code, ask a colleague or sit in a meeting to find out. [Atlassian's 2025 developer experience research](https://www.atlassian.com/blog/developer/developer-experience-report-2025) found that finding information is developers' biggest source of friction, and half of them lose 10 or more hours a week to it. We model this as up to 20% of engineering time. A small team that rarely uses AI tools sits near 5%. A team shipping fast with AI tools sits at 20%. **PMs keeping everyone up to date.** After every release, the docs need updating, the release notes need writing, and sales, support and leadership want to know what changed. That mostly lands on PMs. We model it as 4 to 12 hours a week per PM, again depending on how fast your team ships. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time searching for answers, so those hours add up quickly. For a US team with 4 PMs and medium AI use, that's about $128k a year of PM time. With heavy AI use, it's over $190k. Neither cost shows up in your accounts, and both grow as AI tools help your team ship more changes every week. ## Three inputs you already know [The calculator](/cost-of-doc-drift) asks three things: how many engineers you have, where they're based and how much they use AI coding tools. Where they're based sets the yearly salary, including the costs on top of it: $180k in the US, £110k in the UK and €95k in the EU. You can change it if yours is different. How much they use AI sets where your team sits in each range. It works out how many PMs you have from one PM for every eight engineers, and shows that sum so you can check it. ## What you get back with Specsight The calculator also shows how much of that cost you'd get back. Specsight reads your code, describes every feature in plain words and updates that description each time you ship. So engineers can look up how a feature works instead of digging for it, and PMs don't have to rewrite the docs after every release. We assume that gives back 70% of the engineering time and 90% of the PM time. These are our own assumptions, not measured results, and the calculator shows them next to the number. ## How to check your number Every input is on the page, along with where each figure comes from. If the result looks too high, look at the two ranges first: the share of engineering time and the PM hours a week. Lower them and the number drops. The quickest check is your own team. Ask your engineers how many hours last week went on working out how something works, and ask your PMs how long the last release notes took. ## What to do with your documentation drift number 1. **Treat it as a real cost.** Once there's a figure, documentation drift becomes a budget conversation instead of a complaint. Your engineering lead has a number to point to, and finance can weigh it against the cost of fixing it. 2. **Let the code describe what the product does.** People should write down why a decision was made. What a feature actually does is already in the code, so describe it from there. 3. **Try it on your own product.** Connect your codebase and Specsight analyses it, so you can check the number against your real product. [Get started](/signup), or look around the [demo project](/demo/project) first. Source: https://specsight.app/blog/how-much-is-documentation-drift-costing-you --- ### The Silent Release: What Actually Shipped Last Tuesday? **Published:** 2026-05-21 **Category:** product-management **Description:** A silent release is a product change that ships without being announced. Why release notes miss them, and how to catch them before your customers find them. A customer messages support on Friday. Prices they used to see in pounds now show in euros. Your support lead checks Tuesday's release notes and finds nothing about currency, so they ask engineering. It turns out a default got changed while an engineer was tidying up some code. The team didn't know it shipped. It wasn't in the release notes because it was never meant to be a change at all. That's a silent release: an unannounced change that customers notice before your team does. ## Release notes describe the plan, not what shipped Release notes are usually written from the sprint's tickets. But a ticket is written before the work starts, so it describes what the team planned to build. What actually ships is different. Scope gets cut, edge cases come up, and small fixes happen along the way without a ticket. None of that makes it into the notes. It's the same reason [product documentation falls out of sync](/blog/why-product-documentation-falls-out-of-sync). ## Small changes cause the biggest surprises Big features get attention. Marketing announces them, and if one breaks, the team notices fast. The surprises come from the small changes that ship alongside: a limit that drops, a button that moves or disappears, a default that flips. They're not in the release notes, and customers find them first. Then support starts hedging ("I think it works this way"), and customers notice that too. ## An example Say your team ships an update called "Files now upload in bulk". That's the headline, and it's in the release notes. But the same release also changed the size limit to 20MB, removed the Save draft button and fixed uploads that got stuck at 99%. A customer who used Save draft every day will notice on Monday morning. Specsight lists every one of those changes in plain words, not just the headline: ![A release described in plain words: upload 10 files at once, size limit now 20MB, Save draft button gone, uploads stuck at 99% fixed](/images/blog/example-release.png) ## How to catch silent releases You can't fix this by asking engineers to fill in a better template. That never survives a busy week. You catch silent releases by looking at what actually shipped: the code. Specsight keeps a plain description of how each feature works. When a release ships, it compares the new code with that description and writes down what's new, what changed, what's gone and what got fixed, including the ones that weren't planned. "What changed last week?" stops being a meeting and becomes a link. That's the idea behind [product observability](/blog/product-observability-missing-dashboard). --- Browse every release Specsight has recorded on its own product in [the demo changelog](/org/specsight-demo/projects/00000000-0000-4000-a000-000000000002/changelog). No account required. To see what your own releases change, [get started](/signup). Source: https://specsight.app/blog/the-silent-release --- ### Comprehension Debt: The Real Cost of AI-Assisted Coding **Published:** 2026-04-23 **Category:** engineering **Description:** AI tools help your team ship code faster than it can read it. That gap is comprehension debt. What it is, why it grows with every release, and how to manage it. Picture a standup. A PM asks what happens when a customer uploads a file over the size limit. Three engineers look at each other, and the one who shipped the upload change last week opens the code to check. They built it with Claude's help: they described what they wanted, checked what came back, the tests passed and it shipped. A week later, none of them can say for sure how it behaves. That's comprehension debt: the gap between what your team ships and what it understands. ## What is comprehension debt? Technical debt is a shortcut you know about. An engineer chose a quick fix, and they can point to where it lives in the code. Comprehension debt is behaviour your team shipped but can't explain right now. It's not that the code is complicated. It's that the team never went through it closely in the first place. You can find technical debt by reading the code. Comprehension debt is harder to spot, because reading the code closely is the step that got skipped. ## Why AI-assisted coding makes it grow When engineers wrote every line by hand, reviewing a change meant following their thinking: which edge cases they'd covered and which they hadn't. With AI tools, changes get bigger and come faster. A review is more likely to check that the tests pass and the code looks reasonable, which is a quality check, not understanding. The [DORA 2024 report](https://research.google/pubs/dora-accelerate-state-of-devops-2024-report/) measured part of this: more AI adoption goes with less stable delivery, meaning more code shipped and more rework. My reading of it, which is an opinion and not a study, is that teams now ship faster than they can follow what they shipped. ## Specs used to come first. Now they come after It used to work like this: a PM wrote a spec, engineers built from it, and the spec became the reference. It went out of date over time, but at least it described what the team planned to build. Now a lot of work doesn't start with a spec. An engineer describes the change to Claude, ChatGPT or Codex, refines what comes back and ships it. The plan shifts between the first prompt and the release, so the ticket describes what the team hoped for, not what went out. That means the only reliable description of what shipped is one read from the code, after each release. ## How to manage comprehension debt - **Write down the why yourselves.** Decisions and trade-offs live in people's heads, so they have to be written down by people. - **Get the what from the code.** A plain description of how each feature works, updated with every release, that a PM, support or sales can read. - **Check it as a team.** When the description is wrong, your team corrects it, so it keeps getting better. Specsight does the second part. It reads your code, describes every feature in plain words and updates that description every time you ship. It can miss or misread something, which is why your team can correct any part of it. That's what I call [product observability](/blog/product-observability-missing-dashboard). AI tools aren't going to slow down. The teams shipping fastest need this most, because they're the least able to rebuild the picture from the code when a customer asks. --- See it on Specsight's own product in the [demo project](/demo/project). No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/comprehension-debt-ai-assisted-coding --- ### Nobody on Your Team Can Explain the Whole Product **Published:** 2026-04-14 **Category:** product-management **Description:** Product knowledge lives in people's heads and leaves when they do. Why that slows onboarding and handovers, and how to keep it when your people move on. Pick a feature that's been in your product for over a year. Ask a PM, an engineer and a support lead to explain exactly how it works: what happens when a customer hits a limit, or tries something unusual. You'll get three different answers. All partly right, none complete. ## Product knowledge is spread across people The engineer who built billing knows its edge cases. The PM who designed permissions knows the trade-offs. The support lead knows which parts confuse customers. Each has a piece. None has the whole picture. That's normal when a product grows for a few years while the team changes around it. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time searching for answers, and a lot of that is waiting for the one person who knows. When that person leaves, their piece of the product knowledge leaves with them. ## Every release makes it worse Every release adds more behaviour, and features start affecting each other: permissions change what billing shows, notifications depend on the plan, onboarding has three versions depending on how people signed up. The product grows faster than any one person's understanding of it. Teams that ship faster, especially with AI, see the gap grow faster too. ## It hurts most when people join or leave A new hire learns the product by booking calls with five colleagues and piecing their answers together. That costs the new hire weeks, and costs everyone else hours. A PM who moves to another team hands over documents that were last accurate months ago. A new support lead gets questions about features they've never seen. What a new person really needs is product knowledge they can look up: open any feature and see how it works today, and what changed recently, without asking around. ## Why writing more docs doesn't fix it The usual fix is a documentation sprint. [DORA's research](https://dora.dev/capabilities/documentation-quality/) links good documentation to better team performance, so the instinct makes sense. But [docs fall out of sync](/blog/why-product-documentation-falls-out-of-sync) as soon as the product changes, and keeping them updated is extra work with no deadline. A sprint gives you pages that start going stale the day it ends. ## Keep the knowledge when people move on Your code is the closest thing you have to an accurate record of how the product works. Most people can't read it, and it doesn't explain why decisions were made, but it's far closer to the truth than any one person's memory. Specsight reads it and describes every feature in plain words, using [Context/Action/Outcome scenarios](/blog/context-action-outcome-format). Every time you ship, it updates what changed and keeps the history. Your team can correct anything it gets wrong. So a new hire can learn the product before booking a single call, and when a colleague leaves, what they knew about the product stays. That's a [living product specification](/blog/what-is-a-living-product-specification). --- See every feature of a real product on [one map](/org/specsight-demo/projects/00000000-0000-4000-a000-000000000002/feature-map), read from Specsight's own code. No account required. Or [get started](/signup) with your own product. Source: https://specsight.app/blog/nobody-can-explain-the-whole-product --- ### Why Your Confluence Pages Go Out of Date **Published:** 2026-04-07 **Category:** product-management **Description:** Confluence pages about how your product works go out of date with every release. Why it happens, what to keep in Confluence, and how to keep the rest updated. Most teams have the same Confluence story. A great spec was written two years ago: thorough, with edge cases and diagrams. Today a good part of it is wrong, and it's hard to tell which part. That isn't really a Confluence problem. Notion and Google Docs have it too. Any page that describes how your product works has to be updated by hand every time the product changes, and that's the part that falls behind. ## Why Confluence pages go out of date A page gets written once, when there's time. The product changes every week. Every release makes some page a little less true, and nothing tells the page's author it happened. Updating the page isn't part of shipping, so it waits until a customer complains or a new hire asks why it's wrong. Teams that ship with AI tools see this faster, because they release more changes than a person can write up. It's the same reason [product documentation gets outdated](/blog/why-product-documentation-falls-out-of-sync) everywhere else. ## What to keep in Confluence Confluence is good for the things only people can write down: - decisions and the reasons behind them - plans and roadmaps - meeting notes - onboarding guides and processes - runbooks None of these change when the code does, so those Confluence pages stay true until your team decides otherwise. ## How to keep your Confluence pages up to date For the pages you keep: 1. **Give each page an owner,** so it's clear who fixes it when it's wrong. 2. **Put a "last checked" date at the top,** so readers know how much to trust it. 3. **Archive pages that haven't been opened in a year.** A stale page that turns up in search does more harm than a missing one. 4. **Link instead of copying.** When two pages describe the same thing, one of them goes stale first. ## Stop describing how the product works by hand The pages that go stale fastest describe how the product works: which features exist, what the limits are and what changed in the last release. You don't need to write those, because the answer is already in your code. Specsight reads your code and describes every feature in plain words. Every time you ship, it updates what changed. It can miss or misread something, so your team can correct it. That's [product observability](/blog/product-observability-missing-dashboard): a view of how your product works today that you don't keep up to date by hand. So keep Confluence for decisions and plans, and let the code describe the product. For a side-by-side of the two, see [Specsight vs Confluence](/compare/confluence). --- See a product described from its own code in the [demo project](/demo/project). No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/specsight-vs-confluence --- ### Context, Action, Outcome: A Better Format for Product Specs **Published:** 2026-04-03 **Category:** product-management **Description:** Context/Action/Outcome is a simple format for product specs, clear enough to check and plain enough for the whole team. What it is and the rules behind it. Most product specs are either too vague or too technical. Too vague looks like "users can manage their account settings". Which settings? What happens if the email is already taken? Every line raises more questions. Too technical looks like Given-When-Then test syntax. It's precise, but most PMs find it hard to read, and most support teams have never seen it. The **Context, Action, Outcome** format sits in between: specific enough to check, plain enough for the whole team. ## What is the Context, Action, Outcome format? Context, Action, Outcome is a way to write a product spec as short scenarios. Every scenario describes one situation in three short parts. - **Context** is where the user is when it happens: "customer on the upload page". - **Action** is what they do: "uploads 10 files at once". - **Outcome** is what the product does in response: "all 10 upload and show in the file list". Put together: > **Context:** customer on the upload page > > **Action:** uploads 10 files at once > > **Outcome:** all 10 upload and show in the file list Everyone on the team can read that, check it by trying the product, and send it to a customer. Scenarios come in three kinds. Most docs only describe the first one, and support needs the other two most. Here's one of each for the same upload page: - **Normal flow:** uploads 10 files at once, and all 10 upload and show in the file list - **Edge case:** uploads a 25MB file, and it's rejected with a message about the 20MB limit - **Error:** the connection drops during an upload, and the file is marked as failed with a button to try again Edge cases are limits and unusual situations, and they're where a lot of support tickets start. ## Context, Action, Outcome vs other spec formats - **Free-text docs** are easy to write vaguely. "Users can filter results" says a feature exists, not how it works. - **User stories** ("As a user, I want to...") describe what you plan to build, not what shipped, and skip edge cases. - **Given-When-Then** has the same three-part shape, but it's written for automated tests, not for people. Here's the same scenario both ways: > **Given-When-Then:** Given a customer is logged in and on the upload page, When they select 10 files and click Upload, Then all 10 files upload, And the file list shows 10 files > > **Context, Action, Outcome:** customer on the upload page / uploads 10 files at once / all 10 upload and show in the file list Both say the same thing. One is written so a test can run it, the other so your whole team can read it. ## The rules Specsight follows A format only helps if it's used the same way every time. These are the rules Specsight follows when it writes a scenario: 1. **Context describes a situation, not an action.** "Customer on the upload page", not "customer clicks upload". The action goes in Action. 2. **The same situation uses the same words,** so scenarios about the same page group together. 3. **Each part is a short phrase,** 5 to 15 words, like a cell in a table. 4. **A non-engineer has to understand it.** Screens, messages, emails and what's allowed, never code names or error codes. 5. **Only things users can actually reach.** Unused code doesn't get a scenario. 6. **Every option gets its own scenario.** Paying by card and paying by PayPal are two scenarios. 7. **A scenario only changes when the product does.** When a release ships, a scenario is rewritten only if what it describes actually changed, so its history shows real changes. ## Why the format matters Because each scenario covers one situation, a release that changes one thing only updates one scenario. Everything else stays as it was. That's what lets [a living product specification](/blog/what-is-a-living-product-specification) keep itself up to date. It's also why one spec works for the whole team. Product, sales, support and new hires all read the same plain descriptions, which is the core of [product observability](/blog/product-observability-missing-dashboard). --- See real scenarios in the [Specsight demo](/demo/project), read from Specsight's own code. No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/context-action-outcome-format --- ### What Is a Living Product Specification? **Published:** 2026-03-31 **Category:** product-management **Description:** A living product specification describes how your product works in plain words and updates itself from your code with every release. Here's how it works. Most product documentation is out of date a week after it's written. A change ships, the page stays the same, and the next person to read it gets the wrong answer. A living product specification fixes that by updating itself. ## What is a living product specification? It's a plain-language description of how your product works, kept up to date automatically from your code. Every time your team ships, it changes to match. A living product specification is written for the whole team, not just engineers. A PM, a salesperson or a support agent can read it and understand it. (If you're wondering why normal docs go stale in the first place, I covered that in [why product documentation falls out of sync](/blog/why-product-documentation-falls-out-of-sync).) ## What it looks like It's organised by feature, the way your team already talks about the product: file upload, billing, invitations. Each feature has a list of **scenarios**. A scenario is one situation, described in three short parts: > **Context:** customer on the upload page > > **Action:** uploads 10 files at once > > **Outcome:** all 10 upload; any file over 20MB is rejected with a message That's it. You can read it without knowing any code, and you can check it by trying the product. Scenarios cover the normal flow, the edge cases (where a lot of support tickets come from) and the errors. More on the format in [Context, Action, Outcome](/blog/context-action-outcome-format). ## How it stays up to date Here's what happens when the product changes. 1. **Before:** the upload scenario says customers can upload one file at a time, up to 10MB. 2. **A release ships:** your team adds bulk upload and changes the size limit. 3. **After:** Specsight reads the release and updates the scenario: 10 files at once, up to 20MB each. 4. **History is kept:** the old version stays, with the date it changed. When a customer says "this used to be one file at a time", support can check in a minute. ![A release described in plain words: upload 10 files at once, size limit now 20MB, Save draft button gone, uploads stuck at 99% fixed](/images/blog/example-release.png) That's the difference from a normal spec: a living product specification follows the product without a person rewriting it. Specsight only updates what a release actually changed. It can occasionally miss something or get it wrong, so your team can edit any scenario. ## Who it's for - **Product managers** see what actually shipped, not what was planned. - **Customer success and support** know about a change before customers ask. - **Sales** can check how a feature works before promising it on a call. - **New hires** can read how the whole product works on day one. It's the core of what I call [product observability](/blog/product-observability-missing-dashboard): being able to see how your product works, and how it changes, without asking engineering. --- See how features change from release to release in [Specsight's own changelog](/org/specsight-demo/projects/00000000-0000-4000-a000-000000000002/changelog), read from its code. No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/what-is-a-living-product-specification --- ### Why Product Documentation Gets Outdated (and How to Keep It Updated) **Published:** 2026-03-24 **Category:** product-management **Description:** Why product documentation goes out of date, and three ways to keep it updated: manual upkeep, AI-assisted updates, and product knowledge read from code. A customer asks support a question. Your colleague opens a help page written eight months ago and answers from it. Later it turns out the feature changed in January, and the page never did. Outdated product documentation happens in every company. [Atlassian's 2025 research](https://www.atlassian.com/blog/state-of-teams-2025) found teams spend about a quarter of their time searching for answers. Most teams treat outdated docs as a discipline problem: if only people kept them up to date. They won't, and it's not because they're lazy. It's because of how docs get made. ## Docs describe the plan. The product does something else. Product documentation is usually written before or during the build. Then the build changes things: scope gets cut, edge cases come up, small fixes ship without a ticket. The docs describe what was planned. The product does what was built. By launch day the docs are already a little wrong, and they don't get fixed, because the team is on to the next thing. Every release, the gap grows. [DORA's research](https://dora.dev/capabilities/documentation-quality/) has found a clear link between documentation quality and how well teams perform, so this matters. But keeping docs updated is always a separate job, done by hand, after the real work is finished. ## The docs have no owner after launch During planning, the PM owns the spec. During the build, engineers own the code. After launch, keeping the docs updated isn't part of any role. Process rules like "update the docs before closing the ticket" sound sensible and rarely survive a busy week. ## The code is the most accurate record you have Your code is the closest thing you have to an accurate description of how your product works today. It's not the whole story (some things depend on settings or other services), but it's far closer than a page written months ago. The problem is that most people who need answers can't read code. So companies write product documentation to translate it, once, and hope it keeps up. ## Three ways to keep product documentation updated **1. Write and update docs by hand.** - **Works for:** things only people know, like why a decision was made, how a process works, or onboarding guides. - **Falls short on:** how the product behaves, because that changes with every release. Each change has to be noticed, found in the docs and rewritten by a person. **2. Use AI to help update docs.** Ask an AI tool to rewrite a page after a release, or use a docs tool that suggests edits. - **Works for:** speeding up the writing, when you already know what changed. - **Falls short on:** finding the change in the first place. A person still has to spot it and say which page to update. A change that goes unnoticed never reaches the docs. **3. Read product knowledge from the code.** A tool reads how the product works from the code and updates it on every release. - **Works for:** "how does this work today?" and "what changed?", the questions product, sales and support ask every week. - **Falls short on:** the why behind decisions. It can also miss or misread something now and then, so your team needs to be able to correct it. That third option is what Specsight does. It reads your code once and describes each feature in plain words. Every time you ship, it updates only what changed, keeps the history, and lets your team fix anything it got wrong. Using Confluence today? [Here's how the two fit together](/blog/specsight-vs-confluence). Most teams end up using the first and third together: people write the why, and the code supplies the what. [That's what a living product specification is](/blog/what-is-a-living-product-specification), and it's the core of [product observability](/blog/product-observability-missing-dashboard). --- See what this looks like on a real product in the [demo project](/demo/project). No account required. To see your own product, [get started](/signup). Source: https://specsight.app/blog/why-product-documentation-falls-out-of-sync --- ## Optional - Homepage: https://specsight.app - Blog index: https://specsight.app/blog - Glossary: https://specsight.app/glossary - Public demo: https://specsight.app/demo/project - Compare index: https://specsight.app/compare - Specsight vs Confluence: https://specsight.app/compare/confluence - Specsight vs Notion: https://specsight.app/compare/notion - Specsight vs Swimm: https://specsight.app/compare/swimm - Specsight vs Mintlify: https://specsight.app/compare/mintlify - Specsight vs Jira: https://specsight.app/compare/jira - Specsight vs Linear: https://specsight.app/compare/linear - Specsight vs GitBook: https://specsight.app/compare/gitbook - Specsight vs Cursor & Claude Code: https://specsight.app/compare/coding-assistants - Specsight vs DeepWiki: https://specsight.app/compare/deepwiki - Specsight vs Driver AI: https://specsight.app/compare/driver-ai - Sitemap: https://specsight.app/sitemap.xml - Terms of service: https://specsight.app/terms - Privacy policy: https://specsight.app/privacy - Contact: https://specsight.app/contact - Sign up: https://specsight.app/signup