The Fire That Explains Itself
On the missing literacy between specification and understanding
The clocks in Le Bon Mot disagreed with one another again. This was not unusual. It was, in fact, one of the café’s more reliable truths — that time, like most things worth examining, refused to align cleanly when observed too closely.
Case sat at the long oak table beneath the leaning shelves, a stack of printed specifications spread before her like a cartographer’s failed attempt to map a coastline that kept moving.
Opposite her, the Librarian polished a glass with the solemnity of a priest who had long ago stopped believing in absolution but continued to respect the ritual.
At the far end, Dave was explaining something to the Djinn with increasing enthusiasm and decreasing precision.
“And so the agents coordinate via the specification contracts,” Dave said, gesturing broadly, “and the implementation becomes effectively disposable—”
“—like napkins?” the Djinn offered, helpfully.
“Not like napkins,” Dave sighed. “More like… scaffolding.”
“Ah,” said the Djinn. “Disposable scaffolding. That sounds… structurally reassuring.”
Case did not look up. She had been here before. Not the café—that was a constant—but this place in the thinking.
The place where everything was correct.
And nothing made sense.
The Problem That Would Not Sit Still
“These are perfect,” Case said at last.
The Librarian inclined her head. “That is rarely a compliment in this establishment.”
“The specifications,” Case clarified, tapping the papers. “They’re precise. Executable. Complete.”
“And yet?”
“And yet,” she said, “I still don’t understand the system.”
The Librarian placed the glass down. Dave stopped mid-gesture.
The Djinn blinked, which for a being of simulated certainty was as close as it came to doubt. From the corner, where the fire had been quietly doing the important work of being warm, there came a soft huff.
Case turned.
Sophie
Sophie had been there the entire time, which was, according to the Librarian, the only proper way for anything important to exist. She was French, by breed, pride and beauty; a french bulldog with opinions and attitude to match.
She sat by the fire with the composure of something that had solved the problem of existence early and found it, on the whole, manageable. Her ears were alert. Her eyes were patient. Her expression suggested that she had been waiting for this moment and was only mildly surprised it had taken so long.
“You don’t understand,” Sophie said, in the tone of one asking whether the sun had considered rising a little earlier.
Case blinked. Dave blinked. The Djinn attempted to blink twice and achieved it.
“You can talk,” Dave said.
“I can question,” Sophie replied. “Talking is often unnecessary.”
The Librarian did not look surprised.
She rarely did when something began to make sense.
The Question Beneath the Question
Sophie rose, padded over, and placed her chin as close to the edge of the table as her small frame allowed.
“You say the specifications are perfect,” she said. “Tell me, what do they explain?”
“They define behaviour,” Case said. “They specify what must be true.”
“Yes,” Sophie nodded. “And what do they mean?”
“They mean…” Case paused. “They mean what the system does.”
Sophie tilted her head.
“That is not what I asked.”
A silence settled. Case frowned.
“They don’t explain why,” she said slowly.
“Mm,” Sophie agreed. “And do they explain how to think about what they describe?”
“No.”
“And yet you expected to understand?”
Case leaned back.
There it was. The small, uncomfortable click of something that had been loose for some time finally finding its place.
The Djinn’s Confidence
“But the specifications are lossless!” the Djinn interjected, brightening. “They encode intent precisely. They are the highest fidelity representation of the system!”
Sophie gazed at him.
“Are you lossless?” she asked.
The Djinn hesitated.
“I… approximate losslessness.”
“And do you understand what you encode?”
“I… simulate understanding.”
Sophie nodded.
“Then you see the difficulty.”
The Djinn did not, but felt that he ought to.
Dave, or The Weight of Knowing
Dave leaned forward.
“So what are we missing?” he asked. “We’ve got context, architecture, guardrails — everything’s there.”
Sophie regarded him kindly.
“You have built a system that is correct,” she said. “But you have not built a system that explains itself.”
Dave opened his mouth, then closed it again. He had, for many years, personally been the explanation. It had not occurred to him that the system might need to take over.
The Librarian’s Memory
“There was a man,” the Librarian said, as though recalling a book she had once shelved and never quite returned, “who believed that programs should be written as literature.”
Case looked up.
“Donald Knuth,” she said.
The Librarian smiled faintly. “You’ve met him, then.”
“In a manner of speaking.”
“And what did he suggest?”
“That programs should be written for people to read,” Case said, “and only incidentally for machines to execute.”
Sophie’s tail, such as it is, gave a small, approving wag alone with the rest of her torso.
The Missing Piece
Case leaned forward again, but differently now. Not hunting for an answer. Arranging one.
“We have specifications,” she said slowly, “which define what is true.”
“Yes,” said Sophie.
“And we have code, which realises those truths.”
“Yes.”
“But we don’t have anything that explains…” She stopped, then corrected herself.
“…that teaches someone how to understand the system.”
Sophie’s eyes gleamed in the firelight.
“Now you are asking the right question.”
On Narrative
“Literate programming,” Case said, the phrase settling into the room like a long-forgotten guest who had been expected all along.
“Not documentation,” Sophie added. “Explanation.”
“Not comments,” Case continued. “Structure.”
“Not after the fact,” said the Librarian quietly. “But as the thing itself.”
Dave sat back.
“So the system isn’t just…” he gestured vaguely, “…built.”
“It is told,” Case said.
“And in being told,” Sophie added, “it becomes understandable.”
The Reordering
Case gathered the papers, stacking them not by feature or dependency, but by something else. Something more like thought.
“So we’ve had it backwards,” she said.
“Most things are,” the Librarian replied.
“Code first,” Case said. “Then tests. Then specifications.”
“And now?” Sophie prompted.
Case looked at the fire.
The Fire
The fire in Le Bon Mot was not large. It did not need to be. It burned with a steady, unambiguous purpose, illuminating without insisting, warming without demanding.
Sophie returned to it, circling once before settling into the place she had always occupied.
“Why the fire?” the Djinn asked, still catching up to the conversation he had confidently joined some minutes earlier.
Sophie did not open her eyes.
“Because,” she said, “a system that cannot explain itself grows cold.”
Dave frowned. “That’s not how thermodynamics works.”
“Isn’t it?” Sophie murmured.
Case stood. Not abruptly. Not dramatically. But with the certainty of someone who had found the thing that had been missing not because it was hidden, but because it had been assumed unnecessary.
“We don’t need better prompts,” she said.
“No,” said the Librarian.
“We don’t need more guardrails.”
“No.”
“We need systems that explain themselves.”
Sophie opened one eye.
“At last.”
The Djinn at the Fire
The Djinn moved closer to the hearth, regarding the flames with something like curiosity.
“If I read such a system,” he said, “would I understand it?”
Sophie considered.
“You would process it more effectively,” she said.
“That is not the same thing,” the Djinn replied.
“No,” Sophie agreed. “But it is closer.”
Case gathered the specifications, but did not leave. Not yet.
There was work to do, and for once it was not the kind that could be delegated, automated, or accelerated. It was the slow work. The human work.
The work of making something understandable.
One of the clocks struck an hour that no other clock acknowledged. No one in Le Bon Mot remarked on it. They had learned, long ago, that agreement was not the same as truth.
And by the fire, Sophie slept.
A system that is correct but incomprehensible will be killed.
A system that explains itself will be remembered and will live on.
Some Further Reading
Literate Programming & Explanation
Literate Programming — Donald Knuth
The original articulation. Not just about mixing code and prose, but about ordering thought for human understanding. The key idea: programs are essays.
The Art of Computer Programming — Donald Knuth
Not literate programming per se, but its spiritual sibling: deeply explanatory, mathematically grounded, and relentlessly clear.
Software as Explanation, Not Just Construction
A Philosophy of Software Design — John Ousterhout
Complexity as the enemy of understanding. A modern echo of Knuth, focused on reducing cognitive load.
Design It! — Michael Keeling
Architecture as reasoning made visible. Less poetic than Knuth, but aligned in spirit.
The Scientific Lens (and Why Sophie Is Right)
Surely You’re Joking, Mr. Feynman! — Richard Feynman
The spirit of inquiry. The refusal to accept what cannot be explained.
The Pleasure of Finding Things Out — Richard Feynman
Understanding as joy. Explanation as the core of knowing.
Platform, Habitat, and Flow
Team Topologies — Matthew Skelton & Manuel Pais
Systems of teams as cognitive architecture. Where explanation becomes organisational.
Accelerate — Nicole Forsgren, Jez Humble, Gene Kim
The empirical backbone. Flow improves when systems are understandable.
The Goal — Eliyahu Goldratt
A novel about constraints—but really about seeing systems clearly. Sophie would approve.
For Fun, and Education
Labyrinths — Jorge Luis Borges
Systems that fold in on themselves. Stories that are the idea.
The Hitchhiker’s Guide to the Galaxy — Douglas Adams
The absurd clarity of explanation. And the dangers of systems that almost—but not quite—make sense.
One last thing…
If the story leaves you with one instinct, let it be this:
When something feels “correct but unclear,”
you are not missing more code.
You are missing the explanation.
Or, as Sophie might put it:
If you cannot sit by the fire and explain it,
you do not yet understand what you have built.