The router: what kind of sentence, and about what

1. What kind of sentence, and about what?

Every sentence is one of four kinds: an answer to something we asked, a correction of something we did, a query (asking us something), or an action (asking us to do something). The kind is decided first, from the words. The subject is decided second. The module receives both.

1. Before the four kinds, the router discards what is not aimed at the app at all: background conversation, or nonsense that fits no kind and no subject. That is where "I didn't understand that" lives. A food-shaped sentence with an unfamiliar food is not nonsense; it goes to food, which searches for it (part 2).
2. The order is deliberate. An answer is checked first because we know exactly what we asked and what an answer to it can look like. A correction second, because "no, it was Dave's" is not a new food even when nothing is waiting. Then query or action, then the subject.
3. A sentence that names new foods and has no "yes", "no", or "number 2" in it is never an answer. That one rule would have kept "two bananas and a quarter cup of cottage cheese" out of the Chobani question.
4. Only the subject decision may involve a model, and only when the words alone can't say what the sentence is about. The three kind decisions are settled by rules.

1b. The same thing as a case table

Kind down the side, "nothing waiting" and "waiting for an answer" across the top, an outcome in every cell. The diagram is only right if no cell is empty or wrong. This is the check a reviewer should run on the code too.

1. The rows are tried in this order. A sentence that fits an earlier row never reaches a later one.
2. "Set aside" always means the same thing: the question is no longer open while the new sentence is handled, so nothing said next can accidentally answer it. It is re-asked in one sentence afterwards, or dropped.
3. Two of this morning's failures are two cells here. The bananas were the first Action row, right column, and today's code has no rule there. The Chobani "Yes" was the second Answer row, applied to a question that should already have been set aside.

Inside the food module

2. Inside the food module

Five doors in, matching the five kinds the router can send: a new food to log, an answer to a question we asked, a correction or an edit, a question about food, a food setting. One central lookup that every path uses. Two tracks that never trade places: which food it is, and how much. One hand-off out, to the part of the app that saves, shows the card and speaks.

Connectors: L the central lookup · J judging the candidates · C that food, chosen · A the amount step · F fit an interpreted measure to the row · M ask a model why the question is stuck (part 3) · U estimate the amount (the person said they don't know) · W the web search · E the estimate-or-enter step · D the hand-off to the app.

1. Back to the router. The router decides from words and never looks anything up; the food module does. So the module gets the first say on "is this food at all", and hands the sentence back marked "not food" when it is not. The router then tries the other subjects, and if none takes it, the "none of ours" cell applies.
2. Correction versus edit. Same door, same machinery after the first box; the difference is only in finding the entry. A correction is about the thing we just did ("no, it was Dave's"); an edit is about an earlier entry ("change yesterday's lunch"). Correcting a confirmation while its question is still open is not a correction at all: it is an answer, caught at the top level. Once the entry is found, a change of food goes to the same central lookup as a new food, a change of amount goes to the same amount step, and a deletion removes the entry.
3. One lookup (F11), one judgement (F12). Every source is searched at the same time, not one after another. The order of sources (your saved foods, then makers and restaurants, then USDA, then Open Food Facts) is how the results are ranked, not how they are fetched. There is one lookup box because there must be one lookup in the code. The judgement states the precision setting's meaning: rows that agree within it are one food, logged at the person's words with the range across them ("Quest bar", flavours as alternatives on the card); rows that differ beyond it are asked about.
4. "Nothing usable" searches first (F16), then decides (F17), and it is never "gibberish". A food-shaped sentence whose food we cannot find, even on the web, is an unfamiliar food, not nonsense. The web search (the maker's or restaurant's own nutrition pages) runs first. If it finds nothing either: when we at least know the kind of food ("a plain bagel"), the app offers an estimate from the kind or to let them enter it; when we don't (a brand we have never seen), it says it can't find it and offers manual entry, by typing the numbers or scanning the nutrition label, with the barcode as a long shot since the name may have been misheard. Whole-sentence nonsense and background talk never reach this module; the router handles them (part 1).
5. Cancel and "I don't know" are answers (F7, F7a, F7b), so they come in through the answer door whenever a question is open. Cancel closes the question and removes the entry from the log, and the app says so. "I don't know" is read by which kind of question was asked: to a which-food question, the offered rows are logged as a range at the person's words, or an estimate is made; to a how-much question, the amount is estimated as a range. The precision setting already decided that we should ask, so it is not consulted again. Neither is ever a dead end.
6. "The same question is never asked twice" means exactly that: a second, different clarification may follow ("which one", then "how much"). When the rules would repeat one, something else is going on, and the rules cannot tell what. That is a model's job: see part 3. One case never reaches it: an answer that names something we did not offer ("strawberry" to a chocolate-oatmeal-mint question) is read by the rules as a new lookup of that product, with the brand kept, before any repeat could happen.
7. Quantity and unit are two things, and an amount can be precise, imprecise, or missing (F6, F20). "3" and "ounces" are read separately. A precise amount is matched to the row's own measures (F23): the row's measure of the same kind the person used, weight or volume; a unit change within a kind (ounces to grams, cups to millilitres) is arithmetic; density is used only when the row gives one kind and the person gave the other. "A big bowl of oatmeal", "half a plate of spaghetti", "a handful", "a heaping teaspoon" are stated amounts, not missing ones: they are interpreted (F24) into a range for that food, always a range, and the detail card shows the words said and how they were read ("a handful of nuts", read as 1 to 2 tablespoons, 100 to 200 calories). Only a truly missing amount goes to "ask or assume" (F21).
8. The entry is in the log from the moment it is said (F4). Each food is written as the person said it, marked as being worked out, while the module resolves it or asks about it. It leaves the log only by cancel (F7b) or delete (F8b). If it cannot be resolved, it stays: with a best estimate, or marked as unresolved, so the person can fix it later (a misheard name, a slip). Nothing said is ever forgotten.
9. A question or a statement, never both (F25). When the module asks, nothing is finished. When it logs, it says what it logged and may add a statement, such as an assumption it made, which invites a correction but is not a question and does not wait for an answer.
10. The hand-off. The module ends by preparing a result: what to save, what the card shows, what to say, and what question stays open. Saving, checking the save, showing the card and speaking are done by the app outside the module, the same way for every module. This is how the code is built today: the module returns write intents and a reply, and the shell applies, verifies, renders and speaks.

2b. The flowcharts behind the dots

One per dotted box, keyed by the box number, each to be drawn on the details page with its own diagram and case table. The one-line scope is what each must cover.

1. Where these come from: the requirements document (sources in section 5, amounts in 6, the precision setting in 6.3, the ladder in 10, corrections in 11, rejection in 12) and the code as it stands, used as a record of the thinking, not as the truth.
2. The clarification ladder is one box on purpose. Today it is spread across several places that disagree; the box is the statement that it should be one thing.

When a model is consulted

3. When a model is consulted

One rule everywhere: the rules run first; a model is asked only at the marked points; it is given the node's own rules and the words as said; it answers in a fixed JSON shape that the rules then apply; it never speaks to the person; and if its answer does not fit the shape, the node takes its own safe outcome. Every model call is recorded in the trace like any other decision.

3b. Every point where a model may be consulted

Anything not on this list runs on rules alone. Each row says why the rules are not enough there, what the model is given, what it must return, and the safe outcome if it fails.

1. What a model is never asked: which food the person meant, whether two rows are the same food, what the amount is, whether to log or ask. Those are the rules' decisions from facts, and a model's guess there is how we got the "meal or snack?" reply.
2. Two model points exist in the code today that are not on this list and should go: the ownership check that decides answer-or-new for anything outside a short list (it is a coin flip), and the general chat reply that answers a food sentence when the food route rejects it.

F1 · Is this about food at all

Given: the sentence the router sent, as said; its kind (an action to log) and subject (food) from the router
Outputs: continue as food; or back to the router as "not food"; or the food part kept and the rest handed back

1. This box exists because the router decides from words and never looks anything up. The module knows food better, so it gets the first say on "is this food". Handing back is normal, not an error.
2. Nothing here reads a list of food names. "Something eaten" is recognised by shape: a noun after "had / ate / drank", an amount with a unit, a brand or product word, a venue.

F2 · One food, several, or a dish

Given: the food sentence as said
Outputs: one food; several foods; a dish with a parent and parts (stated or implied); a saved meal

1. Which words are dish words is data (the rule pack's dish forms), never a list in decision code, and it is a class rule: it must handle omelette, sandwich, salad, wrap, bowl, burrito, smoothie alike.
2. A dish counts once in the day's total: the parent shows the sum of its parts (§7).

F3 · Splitting into foods

Given: the sentence and its shape (one, several, a dish)
Outputs: one part per food: words as said, amount words, brand and variant words, preparation words; a dish's parent

1. The words as said are the one thing every later box must preserve. Renaming a row to these words, or these words to a row, is the fault the assessor found behind the Chobani tube.
2. A model may be used only at F3.6, only to produce the same shape, and never to decide what a food is.

F4 · Putting the entry in the log now

Given: the parts from F3, with their words and amounts as said
Outputs: one provisional entry per part, visible at once, updated in place; removed only by cancel or delete

1. This is the policy Howard set on 2026-09-23: it appears in the log as soon as the person says it, and nothing is lost unless they cancel or delete it.
2. What the app was closed mid-question should do (re-offer the question on next launch, or just leave the mark) is a choice to confirm with Howard; the row above shows the safer reading.

F5 · Classifying the food

Given: one part: its words as said, brand, venue and variant words
Outputs: one of: restaurant, packaged, prepared, basic — and the class rules that apply

1. The class never decides what the food is. It decides which sources are worth searching first, what a serving looks like (a bar, a bottle, a menu portion), and which class rules of §8 apply.
2. Today's code has a packaged-food class list (protein shake, yogurt cup, protein bar, snack bar, bread slice, packaged food). That is a data table of forms, which is allowed; a rule about one product is not.

F6 · Reading the quantity and the unit

Given: one part's amount words, size words and modifiers
Outputs: quantity; unit; size; and one of: precise, imprecise, not-an-amount, missing

1. Quantity and unit are read as two things because the unit is what F23 matches to the row's measures and the quantity is what multiplies it.
2. The last, most explicit amount in one sentence wins when two are said (§6.6). An amount said later, in an answer, beats one said now (§11).

F7 · Reading an answer

Given: the answer as said; the open question's record (kind, offered names and count, what a bare yes means, the rejected list)
Outputs: a choice; a hold; a cancel; a rejection; a wider search; an I-don't-know by kind; a new lookup; a choice with an amount; or the stuck-question consult

1. Every decision here reads the question's record — its kind, the names and count it offered, what a bare yes means — never the question's sentence. That record is written by F25 when the question is asked.
2. A model is consulted only at the end (F7.12), and only to say which of five things happened (part 3). It never picks a food.

F8 · Finding the entry to correct or edit, and what changes

Given: the correction as said; the log; the entry we just did
Outputs: the entry; and one of: a food change (to F11), an amount change (to F20), a deletion, a dish-part change; or a which-entry question

1. A correction never creates a second entry (§11). A food change goes through the same lookup and judgement as a new food, and the result replaces the entry, carrying the amount, the estimate status and any rejection.
2. A correction also seeds the person's default for those words, so the same question is not asked next time (§11).

F9 · Answering a food question

Given: the question as said; the log
Outputs: a number or a list, on a card and in one sentence; nothing written

1. Today's code turned "what were the carbohydrates on the last thing I logged" into a food lookup and said it could not complete the nutrition lookup for that sentence. This door exists so a question is never a lookup.

F10 · Changing a food setting

Given: the setting as said
Outputs: the setting saved by the app and confirmed; or one question for the missing value

1. On 09-20 "from now on just tell me the calories" was answered with "I understood the nutrition question, but I could not find a solid number for that food yet". This door exists so a setting is never a lookup or a question.

F11 · Looking the food up

Given: one food's identity words, brand and class; the rejected list
Outputs: the candidate rows, each with its own name, source and a plausibility flag

1. Every source is searched at once. The source order is how ties are broken among the same product, never the order of fetching (Howard, 09-23).
2. Nothing here renames a row to the person's words, and nothing downstream renames the person's words to a row. That is the fault behind the Chobani tube.

F12 · Judging the candidates

Given: the candidate rows with their names and sources; the words as said; the precision setting; the rejected list
Outputs: one food (a match, a default, or a cluster with alternatives); several (to F13); a confirmation of one; nothing usable (to F16)

1. This is the box the decision core already implements from facts. Its two faults this morning were upstream: a renamed row (F11.7 forbids it) and no plausibility check (F11.4 adds it).
2. The precision setting is read here for exactly one thing: how far rows may differ and still be one food (P).

F13 · The clarification ladder

Given: the clusters that differ; the words as said; the record of what has already been asked about this food
Outputs: one question, with its facts recorded (kind, names and count offered, what a bare yes means); or the estimate; never a repeat

1. The rungs are ordered by how much the evidence concentrates the answer (§5.4). The estimate is the last offer on every list, so a "yes" or an "I don't know" always has somewhere honest to land.
2. Wording rules for any question (§5.4): it adds information and says why; short enough to answer by voice; never makes the person repeat their own words; never exposes a wrong guess; options are real rows, never invented. Wording lives in F25, not here.
3. Today this ladder is spread over several places that disagree (the correction path, the fresh-log path, the wider-search path). This box is the statement that it is one thing.

F16 · The web search

Given: the food's words and brand; what was offered; the rejected list
Outputs: new rows for F12, with their evidence; or "nothing new" with what was searched

1. The model here reads pages into rows; it does not decide what the food is. The rows it returns go through the same checks as catalog rows and are offered by the same ladder.
2. What the search retains (product, serving basis, passage, URL, uncertainty) is the evidence a trace shows (§10.1).

F17 · Do we at least know the kind of food

Given: the words as said; the class
Outputs: the kind is known (to F18) or unknown (to F19)

F18 · Offer an estimate from the kind, or to enter it

Given: the words as said; the amount; the kind
Outputs: a class estimate logged as a range with a caution; or the person's own entered food, checked and saved; or an unresolved entry kept

1. The estimate here is from the kind, as a range, and it is always said to be one. The card is where the person sees what was said, why it is a range, and how to narrow it (§9.4).
2. The barcode is offered honestly as a long shot (Howard, 09-23).

F20 · Precise, imprecise, or missing

Given: the chosen food and its measures; the amount read at F6
Outputs: precise (to F23), imprecise (to F24), or missing / unusable (to F21)

1. This box sorts; it does not compute. The arithmetic is F23, the interpretation of vessels is F24, the decision to ask is F21.

F21 · Ask how much, or assume

Given: a food with no usable amount; history; defaults; the precision setting
Outputs: a question ("How much?"), or the assumed range logged and said

1. The precision setting is read here once (P, job 2). The VALUE of the amount always comes from data: the row's serving, history, the typical-size reference. There is no flat default for anything (§6.1).

F22 · Estimating the amount

Given: the food; the plausible amount range from data
Outputs: a logged range with the assumption recorded and said plainly

1. An assumption on how much is stated, on the entry and in the sentence, and is one correction away. That is the difference between this box and a question: nothing waits.

F23 · Matching the amount to the row's measures

Given: a precise amount; the row's measures (weight, volume, count, size); the food's density and form
Outputs: the quantity fitted to the row: macros and range, the person's unit kept

1. Density is the exception, not the rule: it is used only when the row gives one kind of measure and the person gave the other (Howard, 09-23).
2. The person's unit stays on the entry; the conversion is visible in the trace, never silent.

F24 · Interpreting an imprecise measure

Given: an imprecise amount; the chosen food; the typical-size reference; the vague-serving multipliers
Outputs: a range in the food's unit, marked imprecise, with the words and the reading recorded

1. Imprecise measures are always logged as ranges (Howard, 09-23). "A glass", "a bowl", "a plate" are not special cases with rules of their own; they are amounts whose value is a range, and the setting decides whether that range matters (Howard, 08-27).
2. No size lives in decision code: bowl capacities, spoon sizes and the vague-serving multipliers are data with provenance (§6.7).

F25 · Preparing the result

Given: the decisions and facts for this food, or a question
Outputs: either a finished entry with its card and one sentence, or a question with its record and the waiting entry

1. Question or statement, never both (Howard, 09-23). A statement may state an assumption and invite a correction; that is not a question and nothing waits on it.
2. All wording lives here. No other box composes a sentence, and no decision anywhere reads one.

F26 · How the app delivers it

Given: the module's result: an entry or a question
Outputs: the database updated and checked; the card shown; the sentence spoken; an open question held

1. Today this is the shell's result applier, write repositories, card model and speaker: the module returns intents and a reply, the app applies, verifies, renders and speaks. The box is drawn so the module never does any of that itself.

P · The precision setting

Given: the active profile's numbers
Outputs: a yes/no to two questions: do these candidates differ enough to ask? does this unknown amount matter enough to ask?

1. The setting's only two jobs (Howard, 09-22): decide whether asking which is worth it, and whether asking how much is worth it. It is not a source of numbers.
2. A range that straddles the threshold is surfaced as a range, not turned into a question (§4).

Requirements behind the boxes

Every box carries a small label above its top-right corner saying where its rule comes from. Click a label, here or on any diagram, to read the wording and leave a note on it.

Notes

Every sticky note on every page, newest first. A note is pinned to a box: press the small + in any box's corner. The round button at the bottom right adds a note about a whole page. Each note is a thread: reply under it, and Claude answers there too (its replies arrive with the next version of this page). When Claude says a change is done, check it and delete the note.