Every ticket you pick up carries a hidden set of beliefs. “Move the model to the new server” assumes the new server has the same libraries, that the data arrives in the same shape, that someone will notice if the results drift. None of those beliefs appears in the ticket title, and yet the work succeeds or fails on them. An assumptions log is simply a short, written list of such beliefs, kept with the ticket. This explainer covers what it is, how to write one, and how it works in a machine learning deployment.
The idea in everyday words
Think of packing for a journey. You pack a rain jacket because you believe it may rain; you leave the sandals because you believe the path is rocky. If someone asked you to list those beliefs, you could. An assumptions log asks you to do that for a piece of technical work, before you start, so that the beliefs are visible to you and to everyone else on the job.
Each entry has three parts: the belief itself, how sure you are, and how you would find out if it is wrong. That is all. There is no special tool, no required template and no certification involved.
Why bother when the team already communicates?
Because conversation is lossy. People remember what they said, not what they silently took for granted. Two engineers can share a call about a migration and walk away with different private pictures of the target environment. Writing the picture down shows the mismatch while it is still cheap to fix.
The log also protects your future self. Six weeks after a change ships, you will not remember why you chose a particular batch size or why you skipped a check. A dated line that says “we assumed the nightly feed never exceeds the memory of one worker” tells you what the decision rested on, so you can re-examine it when the feed grows.
How to write one in four moves
- Brain-dump. Set a ten-minute timer and write every condition you can think of that must hold. Do not edit yet.
- Sharpen. Rewrite fuzzy lines until each could be proved right or wrong. “Data is clean” becomes “no column in the daily export is missing more than the usual few records”.
- Rate. Mark each as known, probable or unknown, based on whether you have seen direct proof.
- Plan the checks. For each unknown and each probable line with a big downside, write one action: run a query, read a config, ask an owner.
You will usually end up with eight to twelve lines. Anything beyond that suggests the work should be split into smaller tickets.
A machine learning deployment example
Imagine a team moving a recommendation model from a notebook into a scheduled service. Their log might read:
- Live data has the same columns and value ranges as the training set (probable; check by profiling last week’s records against the training sample).
- The scoring job finishes before the morning email goes out (unknown; check with a timed trial run on a full day of data).
- Someone will notice if recommendations quietly get worse (unknown; check whether any alert or report exists for model quality and name an owner).
- The service account can read the feature table (known; confirmed with a test query).
Those four lines point to a profiling script, a timing test and a monitoring gap. Teams exploring this area often pair a log like this with a written guide aimed at data scientists and engineers who put models into production, using the roadmap for the order of work and the log for the beliefs underneath each step. A companion read on how disciplined practice speeds up model releases shows the payoff side of the same idea.
A second example: a routine database change
The method is not limited to machine learning. Take a scheduled change that adds an index to a busy table. The log could say: the table is small enough that the index builds within the maintenance window (probable; check by timing the same operation on a copy), no application relies on the old query plan (unknown; ask the owners of the two services that read the table), and the rollback script has been run at least once (known; the dry run is attached to the ticket).
Notice that the second line is about other teams, not code. Many technical surprises come from beliefs about who else is affected, so give that kind of line a place in every log.
What the log does not do
It does not predict the future, and it does not guarantee success. It cannot capture beliefs you have not noticed. What it does is shrink the set of unexamined beliefs, which is where the nastiest surprises tend to hide. It also makes handovers smoother: a colleague taking over the ticket can read the list and see in a minute what you were relying on, instead of rediscovering it the hard way.
Where to keep it
Put the log in the first place people look. For many teams that is the top of the ticket description. For longer work it might be a section of the design note or a file in the repository. Whatever the home, give it a heading everyone recognises, and mention it in the stand-up when a line changes status.
A short word on training options
If you want guided learning around operations topics, there are many choices. Among them is a website from India that says it runs certification-oriented courses along with consulting and other services for IT staff. Read its pages to see whether the format suits you; the site describes itself, and this article takes no position beyond that.
Frequent mistakes
- Listing tasks. “Write tests” is a job, not a belief.
- Listing only technical items. Include people, schedules and approvals; they break plans just as often.
- Writing it once. Update status as facts arrive, or the page will mislead.
- Hiding unknowns. Unknown is a perfectly respectable label. It means the check is next.
Quick glossary of the terms used here
- Assumption: something you treat as true without direct proof.
- Confidence: your honest estimate of how likely the belief is correct.
- Check: the action that turns a belief into a fact or shows it false.
- Drift: a slow change in incoming data or conditions, which can quietly invalidate older beliefs.
Try it on your next ticket
Open the ticket you are about to start. Add a heading, write six beliefs, and mark each one. Run the checks on the two riskiest before you begin the main work. After the change ships, return and mark each line as held or failed. The whole routine takes under half an hour and makes the next ticket easier to estimate, because you will hold first-hand proof of which of your guesses usually miss.