The Grandmother Has No Requirements

Code as archeology

Code tells a story of how things were conceived and perceived at a point in time. Over the years this becomes an archeology of layers, deposited by changing business demands, technological shifts, and organizational reshuffling, most of it laid down under the immense time pressure of project-driven notions of achievement. Between the lines you find real treasure. My favourite genre is the comment of the form:

# Pete put this here 18-04-2004 to be changed asap

A single line testifying to both the pressure of the moment and the true nature of permanent fixtures. Pete is long gone. The fix is load-bearing now.

The point about such artifacts is that they only make sense against a narrative the reader must already possess. You need to know who Pete was, what the system did then, what “asap” meant in the political theather of that quarter. The comment is a pointer into a story, not the story itself. This is what makes legacy analysis genuinely difficult, and it is exactly the difficulty that requirements extraction tooling promises to relieve. Feed in the documents and the code, receive user stories, acceptance criteria, non-functional requirements, a traceability matrix. Structured, confident, ready for the backlog.

The question is how much of the story survives the projection.

A well-known domain

When working on abstract tooling, it is sometimes useful to hand it a omain everyone already knows. I have previously fed my SKOS generator Alice in Wonderland. This time I gave my requirements builder Little Red Riding Hood.

The tool did its job. It read the tale, applied its viewpoint schema End User, Staff, Client, System), enforced its network zone model, and produced a functional requirements report. Hilarity ensues, as expected. But the hilarity is worth taking seriously, because the funniest lines in the report are funny precisely because the tool is behaving correctly.

Consider RHD-US-001, filed under the End User perspective, feature Logistics and Goods Delivery,” epic “Supply Chain Execution”: as an end user, I want to transport a basket of bread and sweets through the forest, so that the client receives necessary supplies while they are incapacitated. Priority: Must Have. Network zone: Cross-Zone. Constraint: avoid interaction with unauthorized external entities (strangers).

Every element of this is a defensible reading of the source material.

Or the System perspective, where the woodcutter appears as an automated incident response mechanism: identify and react to cries for help, so that the threat actor is neutralized and the end user is saved. The report even notes its own assumption, that the woodcutter is considered a system component. One can argue with the classification. One cannot call it a hallucination. It is an abstraction, and abstractions of this kind are exactly what the tool exists to perform.

The non-functional requirements are, if anything, better. RHD-NFR-001 derives a security policy from the mother’s instruction not to talk to strangers: strict prohibition of communication with unauthorized external entities to prevent social engineering. RHD-NFR-002 identifies protection against identity spoofing, noting drily that the wolf successfully impersonated the client by using clothing and accessories.
The open questions section then asks precisely what a competent security reviewer would ask: how can authentication be implemented so that an actor cannot bypass identity checks by wearing the client’s nightcap and glasses, and what are the specific parameters for identifying a stranger?

These are legitimate requirements. The source material fully supports them. The wolf did, in fact, defeat identity verification with a nightcap.

What the silences say

The report also contains two sections that read, in full: “No requirements extracted for this viewpoint.” One of them is the Client perspective.

The client, recall, is the grandmother. She is the subject and recipient of the system’s services. She is also impersonated, displaced, and in the older tellings eaten. From her point of view the story is a catastrophic service failure with a partial recovery at the end. Yet she generates no requirements at all, because the source text gives her almost no voice. She does not state needs. Things are done to her and around her. The extraction pipeline, working faithfully from the text, projects her out of the specification entirely.

This is the part of the exercise that stops being a joke. Anyone who has extracted requirements from legacy documentation has met the grandmother. She is the stakeholder the system acts upon but who never wrote a document: the citizen in a public sector case system, the patient behind a clinical record, the customer whose complaint process was designed entirely from the inside. The documentation describes what the organization does, in the organization’s language, and so the extraction reproduces the organization’s blind spots with perfect fidelity. The tool’s silences are as diagnostic as its outputs, but only if you already know someone is missing.

The calibration instrument

Which brings me to why the fairy tale is more than a party trick. Everyone carries the ground truth of Little Red Riding Hood in their head. Reading the report, you can instantly sort the extractions: this one is faithful, this one is a plausible inference, this one is an assumption dressed in structure. When the report proposes that the forest path represents the transition across the public internet boundary, you can evaluate whether that mapping earns its keep, because you know what the forest actually is in the story. The tale functions as a calibration instrument. It lets you observe the extraction pipeline’s epistemic behaviour under conditions where you, the reader, hold complete domain knowledge.

Now run the same tool on twenty years of enterprise documentation. The output looks identical in form. Equally confident, equally well structured, the same tidy traceability matrix, the same Must Have priorities. But the only person who can perform the sorting you just performed effortlessly is someone who knows that domain the way you know the fairy tale. In legacy environments, that is often one person, sometimes nobody. I have argued elsewhere that a system becomes legacy the moment the last person who understood it departs. Machine-extracted requirements sharpen that observation into something operational: the moment that person leaves, nobody in the building can tell RHD-US-002 from a confabulation.

My report prints a disclaimer at the top of every run: all requirements are LLM-inferred and require human validation. I wrote that disclaimer, I believe it, and I also know what disclaimers are worth once a nicely formatted document enters an organization’s workflow. They are cheap. A structured artifact with identifiers and priority columns carries an authority that a caveat in the preamble does not dispel. The fairy tale makes the epistemics visible in a way no disclaimer can, because it lets you feel, directly, the difference between an extraction you can check and one you cannot.

What this means in practice

I draw three working conclusions from this small experiment, all of which have held up in real engagements.

First, machine-extracted requirements are a projection, not a recovery. The pipeline does not reconstruct the story of the system; it projects that story into a schema, and the schema determines what can appear at all. Choosing the viewpoints and zones is therefore not configuration. It is the actual analytical act, and it belongs to someone who knows the domain.

Second, read the empty sections first. Every “no requirements extracted for this viewpoint” is either a true statement about the system or a true statement about the documentation, and the difference matters enormously. The grandmother’s silence in my report was faithful to the source and still described the most important stakeholder in the story.

Third, validation is a domain activity, and domain knowledge is the scarce resource these tools consume rather than produce. The right way to introduce extraction tooling into a legacy programme is alongside the people who still hold the narrative, while they are still in the building, precisely so their knowledge can be spent on sorting inference from fact rather than on retelling the story from scratch. Used that way, the tooling is genuinely powerful. I have delivered a working specification with it, on modest hardware, under constraints most teams will never face. Used as a substitute for the last person who understood the system, it produces something more dangerous than ignorance: a confident, well-structured account that nobody can falsify.

The wolf in the requirements is not the model making things up. The model, on the whole, read the story correctly. The wolf is the well-formatted document itself, wearing the nightcap and glasses of a validated specification, waiting for an organization that has forgotten how to ask what big teeth it has.

The hallucination, in this case, is not in the machine. It lives in organizations that have lost faith in understanding their own business.