Library
Everything published here. Search matches titles, tags, section headings and document text — every term has to appear somewhere in the same document.
All 49 documents
General Chat15
- A pointer rootnote — addresses, not knowledgeThe one rootnote that contains no instructions and no content, only addresses — and why each entry should name the decision at which it becomes relevant rather than the activity it describes.
- A rootnote per tool — the vendor's half and the community's halfEach tool a project depends on deserves its own short rootnote in two layers — the vendor's map of its documentation, and a record of where it catches agents out, which vendors rarely publish.
- Affiliate links on a content siteWhat you link to decides your tooling, and the consent rules decide whether a cookieless story survives.
- Asking an AI to check its own work is not a second opinionResearch finds that asking a model to review its answer, or whether it is sure, can turn right answers wrong — and that correction works when something external can be checked.
- Auditing a context file you already haveA pass over an existing AGENTS.md or CLAUDE.md that decides, passage by passage, what is worth its tokens — and the three questions that decide it.
- Business context for an agent working on commercial softwareThe commercial facts an agent cannot read from a repository, and the decisions that go wrong without them.
- ContributingHow to submit a document, what happens to it during review, and what rights you keep.
- Data handling and privacy for an agent working with real dataWhat counts as personal data, where it must never end up, and the changes that quietly widen what you hold.
- Drafting email an agent does not sendThe draft-and-hand-over boundary for outbound email, and the ways email rendering differs from the web.
- Open source and licence policy for an agent adding codeWhich licences may enter the project, what even permissive licences oblige you to ship, and where code copied from anywhere — including generated code — has to come from.
- Telling an AI it is an expert does not make it more accurateA study of 162 personas found none made models reliably more accurate on factual questions. A role shapes tone and focus; accuracy comes from what you hand over, not what you call the model.
- The canonSeven invariants every document in this library must satisfy, and what happens to one that does not.
- What earns its place in a context fileTwo tests decide whether a passage is worth its tokens, and applying them to twelve rootnotes found that padding accumulates in documents that explain and almost never in documents that constrain.
- Where something sits in a long prompt changes whether it gets usedModels used information at the start and end of long inputs far better than in the middle — at worst, below having no documents. Put material first, the question last, and cut what is not needed.
- Working with AI is a handover problemWhy every session starts cold, what follows from that, and the four layers that turn context into something an agent can be handed.
Coding25
- Documentation standard for agent-maintained projectsA linked set of documents with defined sections and relationships, rather than one long file that narrates the code.
- Faking an external service you do not ownA stateful fake plus a control API, so a real app runs a full journey with no live calls — and the isolation you must build before the first run.
- Four ratios, four different failuresFour ratios used to score code quality, and four different reasons each one measured something other than what it claimed.
- Getting a new domain past security filtersTwo independent causes of a false-positive block, only one of which you can do anything about.
- Handling live secrets in AI coding sessionsGetting a credential from its store into its destination without it ever appearing as text the assistant emits.
- Killing processes safely on a shared machineWhy process-selection commands over-select silently, and the inspect-then-kill pattern that catches it.
- Nothing was wrong, or nothing was examinedFour checks that passed because they had no subjects — three in a scoring tool, and one set that caught this document's own author an hour after he went looking for them.
- Operating something that is live, and what an agent may do during an incidentStop the bleeding before diagnosing, record while acting, and the autonomy rules that matter most when they are under pressure.
- Ship edge deployments on a custom domain, never the platform subdomainFree platform subdomains are blocked as a category by security filters, so a subset of real users silently fails.
- Signed self-updates for a desktop app, hosted on object storageWiring an updater keypair, a version manifest and a public bucket, and the flags that make uploads silently do nothing.
- Signing and notarising a macOS app for direct distributionThe certificate types, the notarisation flow, and the build setting that silently ships an unnotarised DMG.
- Supply-chain security baseline for AI-assisted developmentWhat an agent should check before installing a dependency, and which files it must never modify without a shown diff.
- Supportability for an agent working on software people useWhere people get help, which versions are supported, and what an error message, a log line and a diagnostic bundle must and must never contain.
- Test output against the tools people actually haveA file format verified only by the reader you wrote is verified against your own assumptions.
- Testing a desktop app on a disposable Windows VMDriving an interactive Windows session over SSH, and why testing as an admin proves nothing about permissions.
- The strongest evidence against this library, read carefullyA controlled study finds context files do not improve task success and cost 20% more — and its detailed findings are closer to this library's own rule than its headline suggests.
- UI testing an agent can write and run itselfDrive interfaces by stable identity rather than pixels, in tiers, so tests are headless, deterministic and fan out.
- Verification that cannot failThree ways a passing check reports success without ever being able to report anything else.
- We could not get ground truth, and it took three attempts to accept itThree attempts to validate a scoring tool against human judgement, and why all three failing was evidence for the tool's premise rather than against it.
- When the tool disagrees with you, neither of you gets to winWhat to do when a tool built to outrank your judgement is wrong, given that overruling it destroys the only property it had.
- Wiring Polar billing and webhooks without cutting off paying customersAn eligibility gate the sandbox does not enforce, a signature scheme that deviates from the spec it cites, and the webhook orderings that zero a live subscription.
- Working agreement for an agent in this repositoryWhat may be run without asking, what must stop first, and how to report what actually happened.
- Writing about a thing is not doing itSix ways a code scanner mistook writing about a practice for following it, and a seventh found inside the check built to prevent the other six.
- You cannot find it by re-reading the thing that is wrongFour cases where a description and the thing it described drifted apart, none of which was discoverable by reading the description again.
- Your pattern matches the shape you picturedTwo ways text scanning silently misses what it exists to find — soft line wraps, and identifiers in an unexpected form.
Research2
- A research working agreement: gather, and do not concludeWhat an agent may do unattended in a research project, where it must stop, and why uncertainty has to survive contact with it.
- Research context — what has been established, and what has been ruled outThe rootnote a research project needs an agent to read before it starts, and the dead-ends record that is the most expensive thing in any project to rediscover.
Writing4
- A writing working agreement: draft, and do not publishWhat an agent may write unattended, where it must stop, and the two failures that are specific to prose — inventing detail to finish a sentence, and not knowing what you have already said.
- Brand and claims for an agent writing about the productThe exact name, the claims the product never makes, and how other companies' names and marks may be used — brand decisions an agent cannot infer from the code.
- Language and editorial guide for agent-written copyVoice, mechanics and error-message rules, and why inconsistent terminology costs more than any single bad sentence.
- Multi-language support for an agent writing interface codeWhy concatenating a sentence breaks translation, and the assumptions in code that only hold for one language.
Design3
- A design working agreement: propose, and do not shipWhat an agent may change in a design system unattended, where it must stop, and how to tell a problem of taste from a problem of structure before spending a day on the wrong one.
- Accessibility for an agent building and testing interfacesThe conformance level, what gets verified and how, and the failures an agent introduces without noticing.
- Design system context for an agent building interfacesWhy an agent drifts a visual language one plausible value at a time, and the rules that stop it.