A watercolour nocturne: a wall of small wooden drawers in darkness, one drawer open and lit warm amber from inside.

Mantra Field Books · No. 9

The Chat That Forgetshow one person built sixty-five repositories by talking

The thinking, not the code — and the failure that produced each rule.

I am not an engineer. I am a filmmaker and a percussionist who edits television for a living, and there are sixty-five repositories on my GitHub account in Kotlin, Python, Shell, AutoHotkey, Swift, Lua and HTML. All of them were built in conversation.

This book is about the method, because the method is the only transferable part. The applications are mine and specific; the problem underneath them belongs to anybody working this way.

That problem, stated once: the collaborator starts every session with no memory of the last one. Everything here follows from it.

Where the rules actually live

This is the human-readable face of the Mantra Manifest — a repository written for AIs to read, holding fifteen modules and nine API files drawn from twenty-four repositories read in full.

That repository is the operative document and this book does not replace it. If the two ever disagree, the Manifest is right and this needs correcting.


Chapter one

The chat that forgets

The one problem, and what it costs in practice.

Watercolour nocturne: a wiped slate on a dark table with faint chalk ghosts still visible, one amber lamp above.
Wiped clean every morning, and yesterday's reasoning with it.

Working with an AI on a long project is working with a brilliant collaborator who has anterograde amnesia. Each session they arrive capable, willing and completely uninformed about everything the two of you decided.

The cost is specific and it compounds. The same module gets rebuilt in every application, slightly worse each time, because the session building it has never seen the version that already works. A key ring gets reinvented and forgets that an HTTP 429 means slow down rather than this key is dead. A word highlighter gets written from scratch and rediscovers, a year later, that there are no silences between spoken words. A design decision that took three days to settle is quietly undone by the next build, by somebody who had no way of knowing it had been settled.

None of that is the machine being poor. It is the entirely predictable result of a collaborator with no continuity, and the fix is not a better model. The fix is writing things down in a place the next session will read.

Principles, not code

The Manifest holds principles rather than implementations, and the reason is practical: the code is in eleven languages and will be in more. A Kotlin file does not survive translation into AutoHotkey. The principle — try keys in order, treat 429 as a pause rather than a death — survives into any language, and can be handed to a session working in one that did not exist when the rule was written.


Chapter two

The Lego rule

Two apps is the threshold, and why not three.

Watercolour nocturne: a few identical wooden blocks on a dark surface, one amber lamp raking across them.
The same blocks make an aeroplane, a house or a dog. Only the arrangement changes.

Every application is built from blocks, and across a whole account the blocks repeat. A key ring is a block. A word highlighter, a recorder, a clipboard vault, a settings list, a handoff document — all blocks.

The rule that matters is the threshold: a module belongs in the shared repository the moment it exists in more than one application. Not when it is finished. Not when it is elegant. Two.

Why two and not three

Because two is where they start to drift. With one implementation there is nothing to reconcile. With two, a fix lands in one and not the other, and from that moment the two versions are diverging and nobody is tracking it. By three the divergence is old, undocumented, and expensive to unpick.

Waiting for elegance is the more tempting error. The instinct is to extract the module once it is good. But a module extracted at the moment of duplication captures what both apps actually needed, whereas a module extracted later captures whichever version happened to win.

The current set

Fifteen modules and nine API files, drawn from twenty-four repositories read in full. Four apply to everything — the four tests, secrets, handoff, and the design language. The rest apply when the application has that thing in it: key ring, provider router, recorder, word timing, clipboard, accessibility, vault, macro recorder, schedule, illustrated book, versioning.

The illustrated-book module is the newest heavily-used one, and the reason nine web books exist that look like one hand made them.


Chapter three

One repository, never two copies

The highlight that sat on the wrong word for a year.

Watercolour nocturne: two identical keys lying side by side on dark cloth, one amber lamp above, one key slightly worn.
They started identical. One of them got fixed.

This chapter is one mistake, and it is the most instructive one in the account.

Two applications needed the same reading engine. The first plan was sensible-sounding: keep a canonical folder, copy it into both, and hold a rule about keeping the copies in step.

That plan was rejected, correctly. Two copies with a synchronisation rule are still two copies, and the rule is eventually not followed. Not through carelessness — through an ordinary Tuesday when a fix is urgent in one app and the other is not open.

Why this failure mode is worse than most

It is quiet. Nothing breaks. A fix lands in one application, the other keeps the old behaviour, and both continue working. The symptom surfaces months later as a highlight sitting on the wrong word — a small visible wrongness whose cause is a divergence nobody recorded, in a fix nobody remembers making.

The answer is MA_READER_ENGINE: one repository, shared as a submodule where the language allows it, so there is exactly one place the fix can land.

The generalisation

Any rule of the form "and we'll remember to keep these in sync" is a rule that will be broken, and its breach will be silent. Where you find yourself writing one, you have found a place that needs a single source instead.

This is the same principle as the film production's STATE.md — one file, one truth — and the same principle as a single stylesheet shared across nine books rather than nine stylesheets that started identical.


Chapter four

The four tests

And the question underneath all of them.

Watercolour nocturne: four sieves of different mesh stacked on a dark bench, one amber lamp behind them.
Four meshes. What passes all four is probably not broken.

Before writing any test, ask the only question that matters: what could be true that would make this test pass while the feature is still broken?

Each of the four exists to close one answer to that question, and each must be able to fail while the other three pass. A set of tests that all fail together is one test wearing four hats.

  1. The mechanism, alone. Closes the logic is wrong. The function does what it claims, in isolation, with nothing else involved.
  2. The real thing, once. Closes the logic is right but nothing calls it. One genuine end-to-end run against the actual service, the actual file, the actual screen. Not a mock. This is the test people skip and it is the one that catches the embarrassing failures.
  3. The ugly cases. Closes it works when the world behaves. No network. Empty input. A file that is not what its extension says. A screen 360 pixels wide. A key that has been revoked.
  4. The upgrade. Closes it works on a machine that never ran the old version — and its mirror, that it works on a machine that did. Old settings, old file formats, old URLs that somebody has bookmarked.

What Test 2 actually costs

Test 2 is why API keys exist in this system at all. The Manifest's line on it is exact: keys serve Test 2 and nothing else. They are not for convenience, not for demonstrations. They exist so that exactly one real call can be made and the result inspected.

The discipline that follows is that a feature is not reported as working until a real call has returned a real result and somebody has looked at it. Every book in this series was verified by fetching its published address and confirming the page, the stylesheet and each plate returned 200 over the live URL — not from the local file, which was already known to be fine.


Chapter five

Keys

By reference, never by value — and the day it went wrong.

Watercolour nocturne: a small closed metal box on a dark shelf with a heavy lid, one amber lamp low beside it.
Outside the repository, out of the log, and never read aloud.

The procedure is short and every step exists because of something that happened.

  1. Extract by shape. A key arrives in a file with other text around it. Pull it out by pattern — ghp_, sk_, AIza, gsk_ — rather than by reading the file.
  2. Vault it outside the repository. A directory the version control system cannot see, permissions closed.
  3. Never print it. Not in output, not in a log, not in an error message, not while debugging.
  4. Use it by reference. The key is read from the vault at the moment of the call and never appears in a command line, which is itself a log.
  5. Scan the staged diff before every push. Automatically, for all the shapes, every time.

The day it went wrong

On 20 August 2026 — the day this book was written — a Gemini key was printed to a terminal in the course of inspecting the file it arrived in. The redaction pattern covered AIza, which is the shape Google keys had for years. This key was the newer AQ. format. The pattern did not match, and the key went to screen.

Nothing downstream failed. It was not committed, not logged, not transmitted. But it was on a screen, in a transcript, which is exactly the state the procedure exists to prevent.

The three lessons, in order of usefulness
  1. A redaction pattern is a list of shapes you have already seen. It fails silently on the shape you have not. The failure mode of a denylist is always the new case.
  2. Extract by shape before inspecting — the vault step should come first, so that inspection happens on an already-redacted copy rather than on the original.
  3. Say it immediately and plainly. The temptation with a small exposure that harmed nothing is to move on quietly. Rule four exists for exactly this moment, and a key exposure reported late is worth much less than one reported in the next sentence.

Chapter six

Nothing appears, nothing disappears

The design rule that is really an honesty rule.

Watercolour nocturne: a row of identical lamps along a dark wall, all lit at the same steady warmth.
Nothing here is waiting to surprise you.

The design language across every Mantra application comes down to one sentence: nothing on the screen appears or disappears. Controls do not slide in on scroll, options do not reveal themselves conditionally, elements do not fade when they think you are finished with them.

Why this is not an aesthetic preference

An interface where things appear and vanish is an interface that is hiding its own state. The user cannot build a stable model of what the application can do, because what it can do keeps changing. Every hidden control is a thing you have to discover twice — once to learn it exists, once to remember the condition that reveals it.

It is also a rule with teeth for AI-built software specifically. A session asked to add a feature will reach for a modal, a drawer, an accordion — because those patterns are everywhere in the training data and they look sophisticated. Forbidding them forces the harder question: where does this actually belong on the page? The answer is usually simpler than the drawer would have been.

The visual half is the same discipline. One background, one accent, three typefaces, no gradients doing decorative work. The field books in this series share a single stylesheet — literally the same file, lifted rather than rewritten — which is chapter three applied to CSS.


Chapter seven

The handoff

Writing the document that lets the next chat start.

Watercolour nocturne: a lantern set down on a dark path at the edge of the light, as if left for somebody following.
Left on the path, lit, for whoever comes next.

A conversation fills up. When it does, everything in it that was not written down is gone — including the reasoning, which is the expensive part.

A handoff document is not a summary of what was built. The repository already contains what was built. It is a record of what was decided and why, so the next session does not helpfully undo it.

What goes in one

The film production runs the strictest version of this, and its protocol is worth stealing whole: a session that ends without writing here did not happen, because the other worker will never know about it. And the rule underneath it — when something becomes a rule, write it down immediately, in one line, because a rule discovered and not written down will be broken within three scenes.

Three scenes is not a figure of speech. It is roughly how long it takes.


Chapter eight

The failures, one rule each

429 is not a dead key, and there are no silences between words.

Watercolour nocturne: a wooden workbench with old cuts and scars in its surface, one amber lamp raking low across the marks.
Every mark is a rule that did not exist before it.

The Manifest exists because of these. Each is a real afternoon lost, and each produced exactly one line.

429 is not a dead key

A key ring tries keys in order and drops a key that fails. An early version treated any error as failure — including HTTP 429, which means you are going too fast, not this key is invalid. The result was a ring that burned through every working key during a burst of activity and then reported that all of them were dead.
Rule: distinguish rate limiting from authentication failure. A 429 means wait; a 401 means move on.

There are no silences between spoken words

Word-by-word highlighting seems as if it should be a matter of detecting gaps in the audio. It is not: in ordinary speech, words run together with no acoustic boundary at all, and gaps appear inside words as often as between them.
Rule: word timing comes from the transcription service's own timestamps, never from analysing the waveform. This was rediscovered from scratch at least twice before it was written down.

The highlight on the wrong word

Chapter three. Two copies of an engine, one fix, months of silence, and then a small visible wrongness whose cause was a divergence nobody had recorded.
Rule: one repository, never two copies with a synchronisation rule.

The module rebuilt because nobody scanned

The most common failure and the most boring. A session builds a settings screen, a recorder, a clipboard store — from nothing, competently, and slightly differently from the four that already exist.
Rule: scan before building. Read modules/ first; if it is not there, search the account, read every implementation, take the best, and then write it down so nobody searches again.

The plausible number

Asked for a count of repositories, a session will produce a number that looks right. Files in the Manifest said 56, then 57. Counted through the API on 20 August 2026: 58. Both earlier figures were low, and both had been written with confidence.
Rule: count it, or do not state it. A number that was inferred rather than measured is a guess wearing a uniform.

The shape of all of them

Every rule in this book is the scar of a specific afternoon, and none of them was obvious in advance. That is worth saying because the finished Manifest reads like a set of sensible principles somebody sat down and reasoned out. It was not. It is a list of things that went wrong, written in the imperative.


Chapter nine

Lift the version that has been hurt

How to choose between four implementations of the same thing.

Watercolour nocturne: several similar hand tools hanging on a dark wall, one visibly worn and repaired, lit warm amber.
Take the one with the mended handle.

Scanning the account for an existing module usually turns up several. The selection criterion is counter-intuitive and it is the single most useful heuristic in this book.

Take the one with the most failures already fixed. Then the one whose comments explain why rather than what. Then the one with tests.

Age and elegance do not enter into it. A clean implementation written last month by a session that had a good idea has met nothing. A scruffy one that has been in an application for a year has met a revoked key, an empty response, a device with no network, a file with the wrong extension, and a user doing something nobody anticipated — and it has a small ugly branch for each.

Those ugly branches are the value. They are compressed experience, and rewriting the module cleanly throws every one of them away while looking like an improvement.

How to recognise it

The good version usually has a comment that reads like somebody was annoyed. "Do not remove this, the API returns 200 with an empty body when the file is still processing." That sentence cost somebody a day. A clean rewrite will not have it, and will spend the day again.


Chapter ten

Say what you did not read

Coverage, and the twelve unopened repositories.

Watercolour nocturne: a bookshelf in darkness with some volumes lit warm amber and a group at the end still in shadow.
The ones in shadow are named, not hidden.

The Manifest carries a file whose only job is to admit what it has not looked at, and it is the reason the rest of it can be trusted.

GroupCountWhat it means
Read in full24Cloned, source and documents read, used to write the modules
Triaged by README only22Classified, confirmed to hold no new module — but the source was not read
Not opened12Archives, mirrors, asset stores. Judged unlikely to hold a shared module. Not verified.

The file calls the last group the honest hole, says they are almost certainly asset stores, and says that if a future scan has room it should start there. It also records that every module came from code read in full with one exception — the versioning module, which is a decision made on 20 August 2026 that nothing in the account follows yet, and which says so in its own opening lines.

Why this file is load-bearing

A document written for another mind to trust has to be checkable. If the Manifest claimed complete coverage, the first session to find an unaddressed repository would have to distrust everything else in it — because it would have no way to tell which claims were verified and which were assumed.

By naming the gaps, the document makes its own reliability legible. That is the same instrument as the What I could not verify chapter closing every book in this series, and the same instrument as rule four. It appears three times in three contexts because it is one idea: the value of a claim depends on the visibility of what it excludes.


Chapter eleven

What the machine is good at

And where a human has to stay in the loop.

Watercolour nocturne: one hand resting on a dark lever, an amber lamp beside it, the mechanism disappearing into shadow.
The mechanism does the work. The hand decides whether the work was worth doing.

Working this way for a couple of years produces a fairly clear picture. The companion book Six Levels of Claude lays out the progression; this is the practical summary.

Genuinely good at

Where a human has to stay

What it costs

Honestly: the API bills are real but modest against what the output would otherwise cost. The time saved on implementation is enormous. The time not saved is on specification and verification — deciding precisely what you want and then checking that you got it. Those two do not get easier, they get more important, and the share of the work they occupy grows as the implementation share shrinks.

Which is a reasonable description of moving from doing the work to directing it, with the same trade in both directions: less execution, more responsibility for whether it was the right thing.


Chapter twelve

One day, seven books

This session as a worked example, mistakes included.

Watercolour nocturne: a stack of finished books on a dark table beside a lamp, the topmost one still open.
Seven of these were not here this morning.

This book was written on 20 August 2026, in the session that also produced the six field books before it. Rather than describe the method abstractly, here is that day.

What happened

The account held 58 repositories at the start of the day, a figure the Manifest had counted through the API that morning. It now holds 65. Seven of the new ones are the field books in this series, each with twelve to fourteen chapters, thirteen to fifteen watercolour plates, a plain-text edition, a README and a handoff document — published, with every page, stylesheet and plate confirmed at 200 over its live address.

The Manifest itself was created the same day. The standard these books were built to is one day old, which is worth stating plainly rather than letting the shelf imply otherwise.

What the method contributed

What went wrong

  1. A key was printed. Chapter five, in full. The redaction pattern did not know the newer Google key format.
  2. Two sessions built the same book at once. A second chat had been given the same brief earlier, created the repository, and painted a complete set of thirteen plates that were found sitting in the working directory. Neither session knew about the other. This is chapter one's problem in its purest form — not a chat forgetting the past, but two chats with no way to see each other's present. It cost one full set of illustrations.
  3. A brief was wrong and had to be corrected. The acoustics book was described as mostly written. Inventorying the existing repository first showed it covered an entirely different subject, so the book was written new and cross-linked instead of summarised. Scanning before building is the rule; it applies to your own instructions too.
  4. Plates were repainted twice for breaking a stated rule — one with numerals on a dial, one duplicating another. The rule said no lettering, so either the plate changed or the colophon's claim became false.
  5. Facts were checked against repositories rather than recalled. Where that was not possible — one collaborator's name on the film — it is flagged as unverified in the book that carries it.
The honest summary

Seven books in a day is not a claim about productivity. It is a claim about accumulated infrastructure: a stylesheet that already existed, a style paragraph already settled, a publishing procedure already proven, and a set of rules that had already absorbed the failures. The first book took the longest by a wide margin, and most of that time went into things the other six then reused.

Which is the entire argument of this book in one observation. The work is not the building. The work is arranging things so that the next build is cheap — and then writing down what you learned, in one line, immediately, before you forget that you learned it.


Apparatus

Sources

The repositories this was written from.

Written from primary material — Mantra Productions' own repositories, read directly on 20 August 2026.


House rule

What I could not verify

Stated as plainly as what I could.