A sour shot is not a diagnosis
Notes on letting rules draw the boundary and a language model choose the move, from an espresso coach I am building.
Generative contour artwork.
Listen to this note
10 minutes · two hosts talk it through
Chapters
Transcript
AlexThis is the audio version of a Field Notes piece by Martijn Hermans. It's about Vetta, an espresso coach he is building, and how much a language model should be allowed to decide.
SamI'm Sam.
AlexAnd I'm Alex. We're both synthetic voices. The script was written by an AI from Martijn's article, and voiced with PodcastD, the podcast tool he builds himself.
SamA new bag of coffee used to mean a few frustrating shots before he found a setting he liked. Vetta is the coach he's building to shorten that.
AlexA small group of testers now use a web version. You log the shot you just pulled. Dose, yield, time and taste. Vetta answers with one next move, a confidence level, a reason, and the source it leaned on.
SamThe article opens with a real run. He ran the web version on his own machine, against a throwaway database, and typed in two shots.
AlexNothing was brewed, but the rules, the sources and the hosted model are the real ones, and the answers are unedited.
SamThe first shot is sour, and ran twenty-two seconds against a twenty-eight second target.
AlexThe second is a separate simulated input. The same recipe at twenty-seven seconds, still sour. It's not a measured result of following the first card.
SamFor the first, the rule locks the move. Two clicks finer, high confidence, and the model only explains it.
AlexFor the second, the rules point to one click finer at medium confidence, but also allow more yield or a higher temperature. The model kept one click finer and listed the other two as options.
SamHigh and medium sound like probabilities.
AlexThey're not. They're categories the rules assign, describing how much freedom the model gets. High locks the move. Medium points to one but leaves room. They're not a measured chance that the advice is right, and the card doesn't make that visible.
SamThen what happened behind the second card.
AlexThe model's first answer cited nothing, and a medium answer has to cite at least one of the passages it was given. Code rejected it and sent the error back for one retry. The retry cited a passage from Lance Hedrick's espresso tutorial, and passed.
SamThat passage describes a standard recipe. Eighteen grams in, thirty-six out, in twenty-eight to thirty-two seconds. A fair source for, twenty-seven seconds is close to normal.
AlexBut it says nothing about why grinding finer is the right move. The check establishes where a citation came from, not whether it supports the advice. And a separate count of the library showed source concentration. Both cards cite the same video.
SamSo, a sour shot is not a diagnosis.
AlexSour usually points to under-extraction. Not enough has been dissolved out of the coffee, and the textbook answer is to grind finer. But a sour shot that ran short, one on target and one that ran long are different situations, and Vetta uses that difference to assign a confidence category.
SamShort and sour is the clearest case, like the first card. Sour and long is the odd one, because long usually means the grind is already fine.
AlexOne possible explanation is uneven extraction, but time and taste alone can't tell him that. The rule still says one click finer at medium confidence, adds a note to check distribution and tamping, and forbids going coarser.
SamAnd he calls that a judgment, not physics.
AlexCameron and colleagues, in twenty twenty, found extraction peaks. Past a certain point, grinding finer gave lower and less repeatable extraction, which they put down to uneven flow through the coffee bed. Lee, Smith and Arshad, in twenty twenty-three, modelled how: a small difference between two flow paths grows, because more flow extracts more, lowers resistance, and draws still more flow.
SamIn that situation a coarser grind could help. And Cameron's paper is in Vetta's own library.
AlexYet the rules forbid a coarser grind for every sour shot, and he hasn't tested that choice.
SamNow the central decision.
AlexIn May he turned down two designs. In one, a rule engine decides and a model reads out the verdict, so the sources are decoration. In the other, the model is free, and the rules are advice it can ignore.
SamWhat he built sits between them. The rules produce a verdict, a list of forbidden moves, and a few reasonable candidates.
AlexIn the high category the model gets no say over the move. Otherwise it can choose any move the rules permit, and the retrieved passages inform the choice. A hold, a rule saying change nothing, is never overridden.
SamThen code checks the answer. A move outside the boundary is rejected, and so is a citation that didn't come from the retrieved passages.
AlexA rejected answer gets one retry with the error attached, as in the run. If that fails, a high or medium rule falls back to the plain rule answer, and a low one says it hasn't got enough to go on. If retrieval or the model takes longer than twenty-five seconds, the rule answer stays.
SamAnd the web version sends the shot's context to a hosted language model for this step.
AlexOne check is missing: whether a cited passage supports the sentence. A semantic support check was planned, and isn't built. An anonymous shots-like-yours prior is built but switched off by default, and testers don't get it.
SamThen the failure story.
AlexIn May he looked at the first forty-nine recommendations testers had received. Twenty-six were hold. Change nothing. And of all forty-nine, twenty were low confidence or had no citation.
SamA hold is right for a shot that already tastes good.
AlexBut for someone still chasing a better one, it's passive at exactly the moment they decide whether the coach is worth their time. Two paths in the rules could explain some of those holds.
SamSour and long was coded as a hold, although his own spec asked for a grind move. The code had drifted from the design.
AlexAnd a balanced shot rated three out of five matched no rule, so it fell through to the default, which holds.
SamHe changed both. Sour and long became the one-click, medium move, with distribution and tamping as a separate tip. A balanced shot rated three now gets a small, low-confidence yield change.
AlexRated four or more, it still holds, on purpose. If it tastes good, leave it. And he hasn't re-measured the hold rate since.
SamWhere does the advice come from?
AlexThe first library mixed three kinds of source on purpose. One person showing it, one explaining the physics, and one measuring it.
SamThe video series Understanding Espresso by James Hoffmann, the blog coffee ad astra by Jonathan Gagné, and a twenty twenty-five paper by Choi, Lee and Chambers on how repeatable espresso is. More practitioners and open-access papers came later.
AlexVideos are split at chapter markers, papers at sections. Every passage keeps its citation, date and licence basis, and one with no citation can't enter. Each source gets a hand-set weight, papers highest, videos lowest. A design choice, not a measure of reliability.
SamAnd duplicates?
AlexRemoving duplicates is not the same as diversity. At ingest, a passage that repeats an existing one almost word for word is dropped. It doesn't recognise the same idea told in different words, and does nothing about balance.
SamWhen he counted, about three quarters of the passages the web version reads came from one creator's videos. Papers were about three percent.
AlexBoth cards cite the same tutorial. On its own that doesn't demonstrate a diversity problem, but the count shows a concentration he needs to investigate.
SamWhere published sources left gaps, he added notes labelled house knowledge, condensed with AI from deep-research queries.
AlexThey sit in a separate collection with a lower weight. The coach cards draw only on published sources. Chat also searches the house notes, but marks them down, so published sources win ties.
SamWhat does the coach remember?
AlexYour last five shots on the same bag, basket size and gear, and whether you followed the previous advice. Shots from another setup don't leak in.
SamThumbs up and down, and whether an applied change was followed by a better rating, add up to a small counting signal that only breaks ties. But almost nobody pressed the rating buttons, so that signal is thin.
AlexFewer attempts is the aim, not a result. He has no measurement yet that Vetta gets anyone to a good shot sooner.
SamThree things come first. A support check, to test whether a cited passage actually backs its sentence, so a card like the second one gets caught.
AlexRe-running the hold audit, taking the May recommendations through today's rules.
SamAnd testing sour and long with real shots, including the coarser grind the rules now forbid.
AlexMartijn made the product decisions: what the coach may decide, which sources to use, where the boundary sits. AI coding agents wrote most of the code.
SamAnd the article was drafted by an AI assistant from the code, his project notes and the recorded run, and goes through his review before it's published.
AlexThe full piece, with the run, the figures and the sources, is on Field Notes.
SamThanks for listening.
Made with PodcastD, the in-house tool I build for turning writing into podcasts. Claude wrote the script from this note; the voices are synthetic (Kokoro (am_michael, af_sarah)) and everything was rendered on my own machine.
A new bag of coffee used to mean a few frustrating shots before I found a setting I liked. Vetta is the coach I am building to shorten that. It started as a tool for two households with the same machine that buy the same beans, and a small group of testers now use a web version. You log the shot you just pulled: dose, yield, time and how it tasted. Vetta answers with one next move, a confidence level, a reason and the source it leaned on.
Below is a real run. I ran the web version on my own machine against a throwaway database and typed in two shots. Nothing was brewed, but the rules, the library of sources and the hosted model are the real ones, and the answers are unedited.

What the run shows
The first input is a sour shot that ran 22 seconds against a 28 second target. The second is a separate simulated input: the same recipe at 27 seconds, still sour. It is not a measured result of following the first card.
The confidence labels describe how much freedom the rules give the model. High and medium are categories the rules assign to each case. High means the rule locks the move; medium means it points to a move but leaves room. They are not a measured chance that the advice is right, and the card does not make that difference visible.
For the first shot the rule locks two clicks finer, so the model only explains it. For the second, the rules point to one click finer but also allow more yield or a higher temperature. The model kept one click finer and listed the other two as other options.
The interesting part is what happened behind the second card. The model’s first answer cited nothing, and a medium answer has to cite at least one of the passages it was given. Code rejected it and sent the error back for one retry. The retry cited a passage from Lance Hedrick’s espresso tutorial and passed.
That passage describes a standard recipe: 18 g in, 36 g out in 28 to 32 seconds. It is a fair source for “27 seconds is close to normal”. It says nothing about why grinding finer is the right move. The check establishes where the citation came from, not whether it supports the advice. A separate corpus count revealed another issue: source concentration. Both cards cite the same video, and both points come back below.
Why the clock matters
Sour usually points to under-extraction: not enough has been dissolved out of the coffee. The textbook answer is to grind finer. But a sour shot that ran short, one that hit the target and one that ran long are different situations, and Vetta uses that difference to assign a rule-confidence category.
Short and sour is the clearest case, as in the first card. Sour and long is the odd one, because long usually means the grind is already fine. One possible explanation is uneven extraction. Time and taste alone cannot tell me whether that is what happened. The rule still says one click finer at medium confidence, adds a note to check distribution and tamping, and forbids going coarser.
That is a judgment, not physics. Cameron et al. (2020) measured extraction across grind settings and found it peaks: past a certain point, grinding finer gave lower and less repeatable extraction, which they attribute to uneven flow through the coffee bed. Lee, Smith and Arshad (2023) modelled how that happens. A small difference between two flow paths grows, because more flow extracts more, which lowers resistance and draws still more flow. In that situation a coarser grind could help. Cameron’s paper is in Vetta’s own library, yet the rules still forbid a coarser grind for every sour shot. I have not tested that choice.
Try a shot
Pick what the shot tasted like and how long it ran. You get what the rules allow and what they forbid. The cards above show what the model did with two of these cells.
All nine combinations
| Taste | Shot time | Rule | The rules point first to | What the model may do | Forbidden |
|---|---|---|---|---|---|
| Sour | Fast, about 22 s | R-01, high confidence | Grind finer, 2 clicks | Nothing to choose. The move is locked; the model words the advice. | Grind coarser, lower temperature, less yield |
| Sour | On target, about 28 s | R-02, medium confidence | Grind finer, 1 click | Any move not forbidden. Listed: grind finer, more yield, higher temperature. | Grind coarser, lower temperature, less yield |
| Sour | Slow, about 34 s | R-03, medium confidence | Grind finer, 1 click, and check puck prep | Any move not forbidden. Listed: grind finer, more yield. | Grind coarser, lower temperature, less yield |
| Balanced | Fast, about 22 s | R-07, high confidence | Hold your settings | Nothing to choose. Only a hold fits. | Every change: grind, temperature, yield, dose, time |
| Balanced | On target, about 28 s | R-07, high confidence | Hold your settings | Nothing to choose. Only a hold fits. | Every change: grind, temperature, yield, dose, time |
| Balanced | Slow, about 34 s | R-07, high confidence | Hold your settings | Nothing to choose. Only a hold fits. | Every change: grind, temperature, yield, dose, time |
| Bitter | Fast, about 22 s | R-06, medium confidence | Grind coarser, 1 click, after fixing distribution | Any move not forbidden. Listed: hold while you fix puck prep, grind coarser, lower temperature. | Grind finer, higher temperature |
| Bitter | On target, about 28 s | R-05, medium confidence | Grind coarser, 1 click | Any move not forbidden. Listed: grind coarser, less yield, lower temperature. | Grind finer, higher temperature, more yield |
| Bitter | Slow, about 34 s | R-04, high confidence | Grind coarser, 2 clicks | Nothing to choose. The move is locked; the model words the advice. | Grind finer, higher temperature, more yield |
Balanced rows assume a rating of 4 or 5 stars with balanced strength. Lower ratings fire different, low-confidence rules, and other rules (dose, ratio, first shot of a bag) can also apply. This table covers the taste and time rules only.
- Illustrative, not a real session
How to read this: the result shows the rule, its confidence category, the first move it points to, and the moves the model may not choose. Without JavaScript, the table shows all nine combinations.
Method and data
Illustrative. Transcribed from the rule table (R-01 to R-07) and the alignment check in Vetta’s code, with a 28 s target. Fast, on target and slow stand for 22, 28 and 34 s; short is more than 4 s under target, long more than 4 s over. The suggested number of clicks is a rule parameter, not a validated adjustment for every grinder. It is not Vetta’s interface and it does not run the real engine.
Rules set the boundary, the model picks inside it
In May I turned down two designs. In one, a rule engine decides and a model reads out its verdict. That makes the library of sources decoration on a decision already made. In the other, the model is free. Then the rules are advice it can ignore.
What I built sits between them. The rules produce a verdict, a list of forbidden moves and a few reasonable candidates. When the rule is in the high category, the model gets no say over the move. Otherwise, the model can choose any move permitted by the current rules, and the retrieved passages inform the choice. A “hold”, a rule saying to change nothing, is never overridden.
After the model answers, code checks it. A move outside the boundary is rejected, and so is a citation that did not come from the retrieved passages. A rejected answer gets one retry with the error attached, as in the run. If the retry fails too, a high or medium rule falls back to the plain rule answer, and a low one says it has not got enough to go on. If retrieval or the model takes longer than 25 seconds, the rule answer stays. The web version sends the shot’s context to a hosted language model for this step.
Who is allowed to decide what?
The rules decide the boundary, the model chooses inside it, and code checks the result. One check is missing: whether a cited passage supports the sentence.
- Built and on by default
- Built, off by default
- Not built or not checked
How to read this: follow the arrows from the inputs to the answer. Solid outlines are built and on, dashed outlines are built but off by default, and the hatched box is not checked.
Method and data
Implementation diagram. Drawn from the rule engine, the validators and the orchestration code. The citation check confirms every cited passage was among those retrieved, and that medium and high answers cite at least one. It does not test support; a semantic support check was planned and is not built.
Status. Rule alignment, citation provenance, the retry and the fallback are in code and on. The feedback prior is in code. An anonymous “shots like yours” prior is built but behind two switches that default to off, and is not part of what testers get.
Twenty-six holds
In May I looked at the first 49 recommendations testers had received. 26 were “hold”: change nothing. Of all 49, 20 were low confidence or had no citation. The number of holds made me look more closely at when the coach was choosing them. A hold is right for a shot that already tastes good. For someone still chasing a better one, it is passive at exactly the moment they decide whether the coach is worth their time.
Looking through the rules, I found two paths that could explain some of those holds. Sour and long was coded as a hold, although my own spec asked for a grind move: the code had drifted from the design. And a balanced shot rated 3 out of 5 matched no rule, so it fell through to the default, which holds.
I changed both. Sour and long became the one-click, medium move from the section above, with the advice on distribution and tamping as a separate tip instead of a replacement for the move. A balanced shot rated 3 now gets a small, low-confidence yield change. A balanced shot rated 4 or more still holds, on purpose: if it tastes good, leave it.
I have not re-measured the hold rate since.
Where the advice comes from
The first library mixed three kinds of source on purpose: one person showing it, one explaining the physics and one measuring it. That was the video series Understanding Espresso by James Hoffmann, the blog coffeeadastra.com by Jonathan Gagné, and a 2025 paper by Choi, Lee and Chambers on how repeatable espresso is. Later came more practitioners and open-access papers where retrieval came up short; they are listed under Method and data below.
Each kind of source is processed in its own way. Videos are split at chapter markers, papers at sections, glossary entries stay whole. Every passage keeps its citation, date and licence basis, and one with no citation cannot enter. Each source also gets a weight I set by hand, papers highest and videos lowest. That weight is my design choice, not a measure of how reliable a source is. It travels with each passage into the prompt; the direction of the advice still comes from the rules.
Removing duplicates is not the same as diversity. At ingest, a passage that repeats an existing one almost word for word is dropped. That does not recognise the same idea told in different words, and it does nothing about balance. When I counted, about three quarters of the passages in the library the web version reads came from one creator’s videos, and papers were about 3 percent. Both cards cite the same tutorial. That alone does not demonstrate a diversity problem, but the corpus count shows a concentration I need to investigate.
Where the published sources left gaps, I filled them with notes labelled as house knowledge, condensed with AI from deep-research queries. They sit in a separate collection with a lower weight and are cited as “Vetta house knowledge”. The coach cards draw only on published sources; chat also searches the house notes but marks them down, so published sources win ties.
Where does an answer's evidence come from, and what travels with it?
Each source is read and split in its own way. A passage only gets in with its citation, and it keeps its date, weight and licence basis.
- Built and on by default
- Not built or not checked
How to read this: left to right, a source becomes an extracted text, then chunks, then a passage in the library. Solid outlines are built. The hatched box is the phone version's gate, which is only half built.
Method and data
Method. Drawn from the ingest manifest, the chunker and the near-duplicate module in Vetta’s code, and from the corpus README. Near-duplicates: MinHash over five-word sequences, 128 permutations, threshold 0.85, checked against everything already in the library; a match is dropped. Hand-set weights (the code calls them trust scores): papers 0.90 to 0.95, blogs 0.88 to 0.90, practitioner videos 0.70 to 0.80, house notes 0.55. In chat, house notes take a further 0.05 penalty. Source mix counted read-only from the collection the web version reads.
Sources added after the first three. Practitioners: Lance Hedrick’s videos, Scott Rao’s blog and a few Decent Espresso videos. Open-access papers: Schmieder et al. (2023) on flow and particle size, Klotz, Winkler and Lachenmeier (2020) on brewing temperature, Uman et al. (2016) on grinding, and Cameron et al. (2020) cited above.
Disagreement. Sources are not reconciled by vote. If the top three passages all mention a move the rules forbid and the rule is not in the high category, the coach says it has not got enough to go on. That check is a keyword match, not a reading of the passages.
Limits. This is an implementation diagram, not a corpus audit. The phone version’s gate checks for repeated runs of eight words; the similarity check beside it is a stub.
What the coach remembers
For each shot, the coach looks at your last five shots on the same bag, basket size and gear, and whether you followed the previous advice. Shots from another setup do not leak in. Thumbs up and down, and whether an applied change was followed by a better rating, add up to a small counting signal that only breaks ties between options the evidence supports equally. Almost nobody pressed the rating buttons, so that signal is thin.
What comes next
Fewer attempts is the aim, not a result: I have no measurement yet that Vetta gets anyone to a good shot sooner. The run and the holds point to three things to do first.
- A support check. Test whether a cited passage actually backs the sentence it is attached to, so a card like the second one gets caught.
- Re-run the hold audit. Take the May recommendations through today’s rules and see what the hold rate is now.
- Test sour and long. Pull real shots in that case, including the coarser grind the rules now forbid, and see whether the rule is right for a home setup.
How this was made
I made the product decisions: what the coach may and may not decide, which sources to use, where the boundary sits. AI coding agents wrote most of the code. This note was drafted by an AI assistant working from the code, my project notes and the recorded run, and goes through my review before it is published.
- Built and on by default
- Built, off by default
- Not built or not checked
- Illustrative, not a real session
I work on products, lead teams and build with AI. More about me and my own AI tools on martijnhermans.nl. Back to Field Notes.