The clinical audit
There are documents that get opened only at the wrong moments. The DPIA for the clinical-triage system was signed in April 2024 and filed in the compliance folder, from which it never came back out, the way no DPIA ever comes back out of the compliance folder. Eighteen months later, someone opens it. Not a lawyer — a consultant who has come in for a security audit, opening it for routine reasons, because he wants to verify that the declared measures match the implemented ones.
The document describes a system that uses a deterministic scoring model, trained on a closed dataset, with explicit rules for classifying the level of urgency. The processing purposes are four. The legal bases are mapped to the correct recital of the Regulation. Data subjects’ rights are listed one by one with the operational procedures to exercise them. Cross-border transfers do not exist, because everything stays in the vendor’s European data centre. The consultant reads, takes a few notes, then looks up and asks the CIO if he can see the system in operation.
The system in operation is a different one. Three months after the DPIA was signed, the vendor replaced the deterministic model with a neural classifier trained continuously on the last six months of clinical data. The dataset is no longer closed. The classification rules are no longer explicit. The official purposes are still four, but a fifth function has been added at the request of the emergency department, and it is a function the DPIA does not contemplate. Cross-border transfers continue not to exist until one day they do, because the vendor switched hyperscaler and now a portion of the traffic passes through an Irish data centre operated by a US-based subsidiary. None of this is documented elsewhere. The system works. Users are happy. Internal audits pass because they limit themselves to verifying that the system exists and produces coherent output.
The consultant turns to the CIO and asks who authorised the fifth function. The CIO replies that it was an urgent request from the emergency lead, handled within a week, with the vendor releasing to production the following Thursday after a staging test. There is a Jira ticket tracking the change, a pull request approved by two reviewers, an internal changelog. Everything in order on the operational plane. The consultant asks whether the DPIA was updated. The CIO looks at him with the expression of someone who never thought it was necessary, because the DPIA belongs to a different circuit, managed by a different person, in a different folder, on a timeline that has nothing to do with the release timeline. The consultant closes the DPIA and stops calling it a DPIA. He calls it a ghost specification, because it describes a system that exists only on signed paper.
An ordinary condition
The ghost specification, contrary to common belief, is an ordinary condition. Anyone who has worked in an organisation that builds software for a regulated client, or for itself under a regulated regime, knows that between the document describing the system and the system actually in operation, after a few months, a distance opens that grows every week and that nobody has been mandated to close. Not because anyone is lying. Because code has a metabolism the specification does not have, and because the lifecycle of the specification, in the software we actually make, is not managed by any tool comparable to those we have for code.
The objection one usually hears against this point is reasonable, and it should be addressed before going further. The objection says: code is the real specification. Documentation is a simplified projection of the system’s behaviour, and it is late by definition, so the only sensible strategy is to keep the code in good order and accept that the rest is literature. It is the code as documentation principle in slightly more sophisticated form, and it has governed software’s engineering culture for at least twenty years. It worked because it rested on an implicit assumption that no longer holds — namely, that software was judged on the basis of what it does when it runs.
The new evaluative status
Software, under the legal regime now consolidating in Europe between 2024 and 2027, is no longer judged only on what it does. It is judged on what it promised to do, and the promise lives in the written specification, not in the executed code. The revision of the Product Liability Directive, adopted at the end of 2024 with a transposition deadline of 9 December 2026, explicitly included software in the notion of product. Which means that the producer of software is liable for damages caused by defects in the product under a strict-liability regime. On this point I have already written an essay titled Mrs. Donoghue’s Last Bottle, returning to the founding case of producer liability in English law of 1932 and projecting it onto contemporary software. What I only sketched there, and want to bring into focus here, is the epistemological consequence of the new regime. The notion of defect, under strict liability, does not coincide with the bug. It coincides with the gap between what one could legitimately expect from the product and what the product actually did. Legitimate expectations, in the absence of other parameters, are reconstructed from the product’s technical documentation, from the producer’s declarations, from marketing materials, from compliance requirements mapped in risk assessments. They are reconstructed, in other words, from the specification.
The Cyber Resilience Act, fully applicable from 11 December 2027, makes the same move on the security side. Conformity is demonstrated through the technical documentation of the digital product, and that documentation includes the risk assessment, the implemented security measures, the up-to-date SBOM, the vulnerability-handling procedures, the support plan and the updates for the product’s lifecycle. The AI Act, for high-risk systems, requires even more extensive technical documentation, defined in Annex IV, including architectural description of the system, training datasets and data-governance procedures, performance and accuracy metrics, the risk-management system foreseen by Article 9, post-market monitoring procedures. They are distinct regulations, with different scopes, but with an identical epistemic structure. The software product has changed evaluative status. It is judged as the correspondence between a written promise and an observed behaviour, and when the two diverge, the judge or the supervisory authority looks at the written promise. Not because they believe the specification is the real system. Because the written specification is the only fixed point on which a judgement can be grounded.
A small framing clarification is needed here, to avoid an easy misunderstanding. I am not saying that the European regime turns the specification into a magic object that holds regardless of the system. The judge or the authority does not just read the document and declare conformity. They compare the document with the system, assess the coherence, accept technical expert opinions. What changes from the previous regime is that the document stops being an appendix to the product and becomes a constitutive part of the assessment, on the same plane as the system’s behaviour. When the two diverge, the document is no longer automatically dismissed as obsolete. The producer must explain why he released a system different from the one described, and that explanation, in litigation, is much more expensive than it is today.
Everything for the code, almost nothing for the spec
Against this shift, the industry has an arsenal of tools for managing the lifecycle of code and almost nothing for managing the lifecycle of the specification. Code has atomic versioning, and when a line changes there is a commit with author, date and message. It has blame, allowing you to trace back the origin of every decision visible in the source. It has tests, which fail automatically when behaviour deviates from a codified expectation. It has deprecation warnings, which signal a promise being withdrawn. It has safe refactor, supported by type systems and regression suites. It has code review, ritualised in pull requests that leave a trail. It has continuous integration, which prevents an incompatible change from entering the main branch unseen. It has branch protection rules, which physically prevent you from bypassing the process. It has rollback in one command, which reduces the cost of error. Each of these tools is the product of an engineering pressure accumulated over the last thirty years, and is now infrastructure of daily practice — so thoroughly metabolised that anyone entering the trade today takes it for granted and struggles to imagine a world without it.
The specification has its version, and that’s it. A DPIA gets signed, dated, archived in PDF, and the moment the system changes there is no automatic mechanism telling the signatory or the delegate that their signature now covers a different system. Architectural decisions recorded in ADRs accumulate in Confluence, in Notion, in SharePoint folders, and nobody re-reads them unless a specific audit demands it. Security requirements attached to contracts get signed, deposited in the CRM, and from that moment exist as back-office attachments until renewal. Risk assessments produced for AI Act compliance on high-risk systems will require periodic updates, but the mechanism linking the update to concrete system changes will be, in the vast majority of cases, a calendar or a contractual trigger, not a code event. The specification, unlike code, has no internal pressure to stay current. It survives in a slow-time zone where the signature counts more than freshness, and where ageing manifests not as functional degradation but as gradual drift away from the reality the document is supposed to describe.
The reasons for this asymmetry are cultural. Technically, tools to treat specifications with the same seriousness as code have existed for decades. Executable specifications in BDD style, test specifications written in Gherkin, formal contracts in languages like TLA+ or Alloy, interface specifications in OpenAPI or gRPC, proof assistants like Lean or Coq. Each of these systems assumes the specification is a first-class artefact, executable or verifiable, alive in the repository alongside the code. In industrial practice, none of this is the norm. The norm is that the specification lives in a Word document, gets reviewed by someone in legal or compliance, gets signed, gets filed, and from that point its fate is detached from the fate of the code.
The agile origin
The origin of this separation is historical and worth reconstructing in some detail. Software culture grew up in opposition to documentation culture, because documentation was perceived as an imposition by waterfall-style engineering management, and Agile won, among other reasons, because it promised to reduce the weight of the document in favour of working software. The Agile Manifesto, signed at Snowbird in February 2001, explicitly reads “working software over comprehensive documentation”. The wording was cautious, because at the bottom of the document the authors wrote “while there is value in the items on the right, we value the items on the left more”, so documentation was downsized, not abolished. But the industrial reading of the two following decades has been more drastic than the original wording. Comprehensive documentation became a synonym for superfluous documentation, and projects that dared produce more than a README, some comments and a handful of diagrams were suspected of residual waterfall practices. The promise made sense in its context, because the software being written in the early 2000s was judged on functional and commercial criteria, and the document was indeed a cost producing little informational value after the project’s first weeks of life. It was also a political cost, because it was often used to impose gate-keeping processes that slowed work without adding quality.
What has changed, and what engineering culture has not yet metabolised, is the evaluative context. The software we write today is sold in regulated markets, integrated into supply chains that treat it as a certified component, subject to compliance obligations that demand living documentation. The document has stopped being the internal tool of a bureaucracy that wants to control developers. It has become the tool through which the product presents itself to the regulator, to the regulated client, to the eventual judge. Engineering culture continues to treat the specification as a by-product of the process, while the regulatory framework is promoting it to primary artefact. The gap between these two perceptions is the ground in which specification debt grows undisturbed.
Spec-driven, BDD, and their limits
It would be dishonest to pretend there are no attempts to close this gap, and some of those attempts are serious. Spec-driven development in the form it has taken over the last two years, with tools like GitHub’s SpecKit and the practice of keeping a CLAUDE.md per project as context briefing for AI agents, tries to move the centre of gravity upstream of the code. The specification becomes the input for assisted generation by an agent that produces code, tests and accompanying documentation in a single coherent pass. The promise is that the specification is executable, in the sense that it produces a system, and is therefore maintained by the pressure to generate working code. It is an interesting direction, and on the projects where I have applied it, it has changed the economics of the work in non-trivial ways. The time I used to spend translating requirements into code has shrunk, but the time spent writing precise requirements has grown — and that is a favourable trade-off, because precision retains residual value even when the code is rewritten.
The limit I see, after some months of practice, is that spec-driven development solves synchronisation between specification and code at the moment of first generation, which is a real gain, but does not solve subsequent drift. Once the system enters production and changes in response to client requests, incidents, shifts in the operational environment, the formalised specification may or may not be updated, and practical incentives play against updating. Updating the specification costs time and rigour, and forces a negotiation between whoever wrote the change on the fly and whoever is custodian of the document. Under delivery pressure, the document loses. Code in production wins always, because it is what users use. The specification goes back to being a ghost, even when written in a formal language.
Executable specifications such as BDD have the same problem, in attenuated form. A Gherkin suite describing the system’s behaviour stays synchronised as long as someone fails it and realigns it, but when delivery pressure rises, scenarios get skipped, marked pending, deleted. I have seen suites of hundreds of scenarios shrink to a few dozen in a year and a half — not because the behaviours described had disappeared from the system, but because the suite had become friction the team no longer had time to manage. Executable specs remain more resistant than a DPIA, because they are code and therefore subject to the incentives of code, but they are not immune to drift. They are only slower to drift. And there is a second, subtler problem. Executable specifications cover functional behaviour well — the part of the system that can be verified automatically. They cover much less of the part that the new European compliance asks you to document — risk assessments, architectural choices, processing purposes, mitigation measures. That part eludes automation, because it is not behavioural, and it remains constitutive of the product as a legal object. No test framework will tell you whether it is still coherent with the system.
A subcategory, not a synonym
One could object, at this point, that specification debt is already included in the general concept of technical debt, and that talking about it separately is an elegant way to rediscover the moon. The objection is formally correct. The taxonomies of technical debt that developed in the two decades after Ward Cunningham’s original formulation, in particular Martin Fowler’s work and that of those who refined the cause quadrant, include outdated documentation as one form of debt. The distinction I propose is economic rather than conceptual. Classical technical debt has natural incentives toward repayment, because it slows you down, irritates you every day, costs you onboarding and development time. Specification debt has almost no incentives until a triggering event arrives, and the incentives it has are bureaucratic and calendar-driven, not operational. This difference justifies treating it as a subcategory with its own dynamics, especially now that the regulatory framework is loading it with value asymmetrically with respect to other forms of debt.
What I call specification debt is the invisible version of technical debt. Technical debt is the price you pay in the form of slower development, recurring bugs, harder onboarding. It is a price you pay continuously, in small instalments, that motivates you to invest in refactoring because you feel the pain. Specification debt you don’t feel. It doesn’t slow down development, because whoever develops doesn’t read the specification, and when they do read it they find it useful as a historical reference but not binding. It doesn’t generate bugs, because the code is already the real specification from the standpoint of execution. It doesn’t impede onboarding, because whoever joins the team learns from the code and from colleagues, not from archived documents. Specification debt produces only one kind of damage, and produces it when an event arrives that forces you to confront the specification as a binding object. A third-party audit. A security incident that becomes a court case. A data subject access request you cannot answer because the processing map was made for a different system. A complaint from a client who has read the contract and declares, with some reason, to have purchased something that was not delivered.
When that event arrives, specification debt becomes visible all at once, and the price is asymmetric with respect to technical debt. Technical debt you pay in instalments; specification debt you pay in a single lump sum, usually higher than the sum of the instalments you would have paid by managing it over time. There is also a difference in the nature of the cost. Technical debt you pay in development time, and that time is yours to control. Specification debt you pay in lawyer time, in external consultants, in extraordinary audits, in imposed remedies, and in reputation — which is the most expensive currency of all because it does not refinance. There is finally a temporal difference no one notices until it lands on them. Technical debt is paid gradually, while you work. Specification debt is paid suddenly, while you are doing something else, usually at a moment when you have no margin. The crises that reveal it always arrive at the worst possible moment, because they are the moment when someone else has decided to look at what you did not look at.
Archaeology and asset
In recent months I happened to work on a compliance assessment for a clinical-flow management system built for a large research hospital, and the client of the client — that is, the final clinical foundation — had requested a security appendix with ten control domains to map against GDPR Article 28 and a list of sector-specific requirements. The original specification of the system had been drafted three years earlier, when the system was a relatively simple data-collection platform. In the meantime the system had grown, had acquired processing modules, had been connected to third-party systems, had changed hosting provider. The distance between the starting document and the current system was enormous. The work I had to do for six weeks consisted essentially of rebuilding the specification from the system — that is, reverse-engineering behaviour to write a new document that would be coherent with reality.
The operational detail of this work is instructive, because it tells you what it actually means to manage specification debt when it is called in. I had to talk to six different people, each holder of an undocumented piece of knowledge. I had to read the code of three microservices that had been added after the DPIA was signed. I had to track down an external vendor to ask which anonymisation algorithm they applied to the data passed through them, because no one on the internal team knew with precision. I had to reconstruct the flow of personal data across five different systems by looking at network configurations and application logs, because the original diagram had become unusable. All this work was foreign to development. It was pure reconstruction of a documentary truth that should have been maintained over time and that instead had to be rewritten from scratch. It was exactly the operation the regulatory regime assumes is never necessary, because the specification should have been maintained along the way, and it was exactly the operation that is almost always necessary, because the way is never managed like that.
On another project, a legal-risk assessment platform for a specialised firm, we decided at some point to migrate the entire stack from Python to Laravel 12. The migration is in progress and we are around seventy-eight per cent done. What I have learned from this migration is that the real asset transferred was not the code, it was the functional specification. The Python code has been largely thrown away and rewritten, the data model has been redesigned, the framework choices have changed radically. What survived is the precise knowledge, formalised in product documentation and in client contracts, of what the system has to do, in what order, with what constraints, against what external interfaces. Without that specification, the migration would have been impossible. With that specification, and with a team that treated it as an active reference during the work, the migration has been hard but feasible.
The difference between this project and the clinical case told earlier is a difference of practice, not of the nature of the specification. In both cases there was a written specification. In the clinical case the specification had been signed and then abandoned. In the migration case the specification was read every two weeks in retrospective, contested when the team found inconsistencies, modified when a product choice changed, integrated when a function was added. It was a living object in the process, not a compliance heirloom. It is the same distinction that separates a flight manual the pilot reads before every take-off from the same manual archived in a library. The same text, two completely different functions, two operational values that cannot be compared. The specification as a transferable asset, and the specification as an asset that ages or does not age depending on how we treat it, are two faces of the same thing.
The tools we still don’t have
A reasonable hypothesis is that the next decade of software engineering will be defined by tools for the specification lifecycle analogous to those the past decade has defined for the code lifecycle. The first serious attempts are already visible. Traceability systems linking specification requirements to the tests that verify them, and the tests to the code changes that touch them, so that when a test changes the system knows which requirement has been impacted and asks for the document update. Drift-detection tools on architectures, comparing declared service topology with observed topology and flagging divergences. Versioning of DPIAs in git repositories with mandatory reviews on every structural change of the system. Product specifications living as versioned objects beside code, with CI failing when the gap between specification and implementation exceeds a threshold.
Let me try to imagine what daily practice might look like in five years, in a team that has metabolised this turn. The DPIA has changed form and lives as a YAML file in a protected repository, with version history, modification authors, an approval process via pull request. When a developer introduces a new processing of personal data, a static-analysis pipeline on the code detects the new flow and automatically marks the pull request as “DPIA-impacting”. The merge stays blocked until the data protection officer reviews and approves the corresponding change to the processing document. AI Act risk assessments follow an analogous mechanism, with drift detectors flagging when the model in production deviates from the metrics declared in the technical documentation. SBOMs update automatically on every build and produce readable diffs that enter product changelogs. None of this eliminates compliance work, but it transforms it from reconstructive archaeology — like the six weeks I spent on the clinical system — into continuous maintenance, integrated into the same rhythm as development. The cultural leap is to understand that documenting the system, under this new regime, is the construction of the legally relevant asset of the product, and not an administrative cost to minimise. Whoever does not do it now will do it in five years after losing a case, and at that point it will be more expensive.
Body and soul
A few months ago, on this blog, I wrote a piece titled Cruft, Not Patina, and the central argument was that software does not know how to age the way material objects do, because the drift between code and the environment in which it runs erodes it faster than engineering culture can metabolise. There was a passage about Unix as an exception, because in Unix the specification detached from the code and became culture, surviving across cycles of full rewriting of the body. That passage closed with a note of cautious optimism on the fact that the specification, when it detaches, is the stable plane that crosses change.
I need to qualify that note. The specification detaches from the code in two different ways, and the difference between the two decides everything. The first way is the Unix one, in which the specification becomes shared culture, described in canonical books, maintained by a community that knows how to apply it to new contexts, and therefore renews itself without losing identity. The second way is that of the archived DPIA, in which the specification becomes a signed document that no one reads anymore, and therefore stays identical to itself while the system becomes something else. In the first case the detachment produces continuity. In the second case the detachment produces a ghost specification. The difference between the two ways does not lie in the nature of the specification. It lies in the practices of those who use it. A specification that is read, contested, modified, re-discussed, applied to new cases, is a specification that lives. A specification that is written, signed, archived, and then ignored until the next audit, is a specification that dies slowly while no one is looking.
Putting the two essays together, the general argument I am trying to build is this. Software has a double problem with time. On the one hand, code does not know how to age, because its environment changes too fast and drift turns it into cruft rather than into patina. On the other hand, the specification, which could be the stable plane that crosses the rewriting of the code, manages to be that only when a constant practice keeps it alive — and in the vast majority of cases that practice is missing. The result is that software, under the legal regime now consolidating in Europe, is entering an era in which both the body and the soul of the product are fragile, and in which the only thing that can hold the two planes together is a discipline of documentary maintenance that engineering culture has yet to build. Software’s engineering culture has not yet drawn the distinction between the two with the clarity that is needed, because it has long treated the specification as a by-product. The regulatory framework now consolidating in Europe is forcing it to draw that distinction, and the price of the next few years will be paid by those who do not notice in time.
Specification debt is the technical debt you don’t see until someone gets hurt. We are accumulating it in silence, in SharePoint folders no one opens, in signed PDFs that are no longer a faithful representation of the systems they certify, in DPIAs filed on the compliance server like monuments. The first major European court case on software product liability under the new regime of the Product Liability Directive will be fought over the specification. When it arrives, and it will arrive soon, the industry will split between those who kept their specification alive and those who only kept on signing it.
Key takeaways
The «ghost specification» is not a rare pathology: it is the ordinary condition of any system that lives long enough. The signed document stays identical while the system becomes something else.
Under the new European regime — revised PLD with transposition deadline 9 December 2026, CRA fully applicable from 11 December 2027, AI Act on high-risk systems — software is no longer judged only on what it does, but on the coherence between written promise and observed behaviour. The specification becomes the legally relevant asset.
Industry has atomic versioning, blame, tests, code review, CI, branch protection for the code. For the specification it has the signature on the last page and the archive. Agile culture read «working software over comprehensive documentation» as abolition rather than as recalibration.
Specification debt is a subcategory of technical debt with a different economic dynamic: you don’t pay it in instalments, you pay it in a lump sum, usually when an audit, a lawsuit or an incident forces you to look at it — and almost always higher than the sum of the instalments you avoided.
Specification detaches from code in two ways: like Unix, where it becomes living culture and survives across rewrites, or like the archived DPIA, where it becomes a monument and dies slowly. The difference is not in the object — it is in the practice of those who maintain it.
Questions & answers
What is «specification debt», and how does it differ from classical technical debt?
Specification debt is the distance that opens up, week after week, between the document describing a system (DPIA, ADR, AI Act risk assessment, contractual requirements, CRA technical documentation) and the system actually in operation. It differs from classical technical debt in economics, not in concept. Classical technical debt has natural incentives toward repayment, because it slows you down every day. Specification debt doesn’t slow down development, doesn’t generate visible bugs, doesn’t impede onboarding — until an event arrives that makes it binding: an audit, an incident, a lawsuit, a data subject access request. At that point it is paid in a single instalment, in lawyers’ and consultants’ time, and almost always higher than the avoided instalments.
What changes with the revised Product Liability Directive and the Cyber Resilience Act for those who build software?
What changes is software’s evaluative status. The revised PLD, adopted at the end of 2024 with transposition due by 9 December 2026, explicitly includes software in the notion of product and applies strict liability. «Defect» does not coincide with «bug»: it coincides with the gap between what one could legitimately expect and what the product actually did. Legitimate expectations are reconstructed from technical documentation, marketing materials, risk assessments. The CRA, fully applicable from 11 December 2027, reinforces the same logic on the security side: conformity is demonstrated through living technical documentation. The specification stops being an appendix and becomes a constitutive part of the assessment.
Don't spec-driven development and executable specs (BDD, OpenAPI, TLA+) already solve the problem?
They solve the initial synchronisation between specification and code, and that is a real gain. They don’t solve subsequent drift. Once the system is in production and changes in response to requests, incidents, environment shifts, the formalised specification may or may not be updated, and practical incentives play against updating. Gherkin suites are more resistant than a DPIA because they are code, and therefore subject to the incentives of code, but under delivery pressure they are skipped, marked pending, deleted. There is also a second problem: executable specs cover functional behaviour well, and almost none of what the new European compliance asks you to document — risk assessments, architectural choices, processing purposes.
Why has software's engineering culture come to treat the specification as a by-product?
For specific historical reasons. Agile culture, from the 2001 Snowbird Manifesto onwards, grew up in opposition to waterfall documentation culture. The original wording was cautious — «working software over comprehensive documentation» with the closing note «while there is value in the items on the right, we value the items on the left more» — but the industrial reading of the two decades that followed was more drastic than the text. «Comprehensive documentation» became a synonym for «superfluous documentation». It worked because software was being judged on functional and commercial criteria. It no longer works, because the regulatory framework is loading the specification with value asymmetrically, and engineering culture has not yet metabolised this.
Concretely, what will practice look like in five years for a team that has internalised the problem?
The DPIA will live as a YAML file in a protected repository, with version history, modification authors, and an approval process via pull request. When a developer introduces a new processing of personal data, a static-analysis pipeline will detect the new flow and mark the pull request as «DPIA-impacting», blocking the merge until the DPO reviews and approves the corresponding change to the document. AI Act risk assessments will follow an analogous mechanism, with drift detectors comparing the production model with the metrics declared in the technical documentation. SBOMs will update automatically on every build. Compliance will become continuous maintenance integrated into the development rhythm, not reconstructive archaeology triggered by an event.
Does specification debt only concern heavily regulated companies?
No, but heavily regulated companies will pay it first. Anyone building software in Europe falls within at least one of the perimeters (PLD for any digital product, CRA for products with digital elements, GDPR for any processing of personal data, AI Act for systems falling into the risk categories). The difference between sectors lies in timing and severity of the confrontation, not in the existence of the risk. The question to ask is not «am I subject?», it is «when will the first event arrive that forces me to confront the specification with the system, and what condition will it find me in?».
The author
