Box 03-01 · Template
LIMITATIONS.md template
How to write down what your system does not do. The four-section skeleton, three worked examples, and a checklist to run before you ship.
Every system I ship comes with a file called LIMITATIONS.md, next to the README. It lists what the
system does not do, what it does in a simplified way, and what broke while I ran it. Software that only
lists its strengths is an advertisement.
This is the skeleton behind those files, as an 8-page PDF.
What is inside
- Why the file exists: the buyer trusts the README more, the next engineer starts from the right place, and I stop lying to myself.
- The template, four sections, ready to copy: By design, Operational, Found by running it, Known rough edges. What goes in each and the one-question test for it.
- How to fill it: lead with the limit as a noun phrase, name the mechanism, say what changing it would take, say which way it fails, date the checks, keep the heuristics you reverted.
- Three worked examples, generic: an AI intake pipeline, a meal-planning app, a RAG support bot.
- An eleven-point checklist to run against the file before shipping. The last point is the real test.
Who it is for
Anyone who ships a system to someone else: a client, a team, a reviewer. It assumes nothing about the stack. The examples use workflows, a web app and a retrieval bot, but the file reads the same for a script.
End of sheet
Back to the vault