Mantra Field Books · No. 9
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.
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 one problem, and what it costs in practice.
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.
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
Two apps is the threshold, and why not three.
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.
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.
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
The highlight that sat on the wrong word for a year.
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.
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.
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
And the question underneath all of them.
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.
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
By reference, never by value — and the day it went wrong.
The procedure is short and every step exists because of something that happened.
ghp_, sk_, AIza, gsk_ — rather than by reading the file.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.
Chapter six
The design rule that is really an honesty rule.
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.
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
Writing the document that lets the next chat start.
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.
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
429 is not a dead key, and there are no silences between words.
The Manifest exists because of these. Each is a real afternoon lost, and each produced exactly one line.
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.
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.
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 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.
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.
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
How to choose between four implementations of the same thing.
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.
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
Coverage, and the twelve unopened repositories.
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.
| Group | Count | What it means |
|---|---|---|
| Read in full | 24 | Cloned, source and documents read, used to write the modules |
| Triaged by README only | 22 | Classified, confirmed to hold no new module — but the source was not read |
| Not opened | 12 | Archives, 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.
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
And where a human has to stay in the loop.
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.
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
This session as a worked example, mistakes included.
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.
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.
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
The repositories this was written from.
Written from primary material — Mantra Productions' own repositories, read directly on 20 August 2026.
README.md for the Lego rule, the four rules of building, the module table and the one-line version. COVERAGE.md for the 24 / 22 / 12 split, the 58-repository count and the note that earlier files said 56 and 57. START_HERE.md for the routing table. modules/four-tests.md, modules/secrets.md, modules/handoff.md, modules/design-language.md, modules/illustrated-book.md, modules/versioning.md.MA_READER_ENGINE — the shared engine of chapter three.HOW_I_MADE_TTT, TTT_MINI, MAHA_TRANSCRIBE_STREAMLIT, AVID_ASSISTANT, KEYRING — the applications the modules were drawn from.STATE.md.House rule
Stated as plainly as what I could.