The project instruction file
Why it exists
Every session with the assistant starts from zero. It reads quickly, and it remembers nothing from the last session, so the most expensive mistakes available to it are the ones that were already made and paid for once. The project instruction file is the fix: a plain text file in the repository, read before any work begins, recording what has been decided and the reasoning that decided it. It is why last month’s decisions survive this month’s session.
How it starts
Small, and on a bad day. The first entry in a file like this is rarely a principle; it is a correction with a date on it: a settled design got unsettled by a fresh session with a good idea, or a draft reached for a figure that was never cleared. Write down the decision and the reasoning that produced it, in full sentences, while it is fresh. From then on the file is read before the work, and that mistake is closed.
How it grows
One rule per failure. A rule enters the file because something went wrong, and it enters together with its reasoning, because a rule without reasoning reads as taste, and taste gets re-litigated by whoever finds it inconvenient. Growth by failure keeps the file honest; every line in it is attached to something that happened.
What belongs in it
Decisions, with the reasoning attached. And the questions that are closed, marked closed, with the argument that closed them, because a closed question with nothing attached looks open.
What stays out
Anything the code or the data already says. The assistant reads the repository at the start of every session; a line that paraphrases it goes stale at the next change, and one stale line costs the whole file its authority. The same goes for numbers the connected systems can answer: the file records rulings about the data and leaves the data where it lives.
The file behind this site
bucca.dk runs on a file like this, and three of its entries show the range. One records which figures are cleared for publication: client results stay off the site until the client clears them, and the file lists the claims already removed, so a future session cannot put one back in good faith. Another records a design decision made twice: the client logos on the front page keep their own colours, though the identity manual argues for a monochrome wall. I decided it twice in the same month, because the first decision never got written down; the entry now says so, and the question has stayed closed since. A third is a trap in the typeface: switch its numerals to the tabular set and punctuation takes a full digit’s width, so “4.5” sets as “4 . 5” and “No lock-in” gains air around the hyphen.
Why it matters more as the work gets longer
In the first month there is little to write; every decision is fresh and the person who made it is in the room. A year in, most of what the assistant needs to know is the arguments that were settled along the way, and the file is the only place they exist. The code holds the outcome of each argument; the file holds why. A long engagement is a pile of settled arguments. The file is where they stay settled.