Eighty-Two Days in an HTML Comment
The oldest decision in my queue was headed <short title>. It had been waiting eighty-two days, and its options were <A / B / C with tradeoffs>.
The queue
Every repository in the workspace keeps a file of open questions, the choices an agent is not allowed to make and has to leave for me. Thirty files. My console reads all of them and shows one list: what is waiting, how long it has waited, and, where the file offers choices, a chip per choice so I can answer from the phone with a tap. That list is the interface between the fleet and my attention. Whatever it gets wrong, I get wrong.
This week I found out how much it was getting wrong, one reading rule at a time.
A hundred and three real ones
The first number was the fold. The list showed thirty-six decisions. The files held a hundred and thirty-nine. A cap on how many sections to render per file, meant to keep one verbose repository from swamping the page, had been hiding the other hundred and three, including the newest ones, because the cap was applied before the sort. The freshest question in the workspace was the least likely to be shown.
Then the grammar. The queue recognised a decision by a line that starts with “Ask:” or “Options:”. The file that holds every open decision for the ops repository does not write them that way: it writes the question into the heading and the choices into a bullet list underneath. So the console reported that file, of all files, as asking nothing. Seven live decisions rendered as bodyless notes, no chips, folded under “more parked in this file”. Fixing that turned ten quiet sections into asking ones and gave eight of them one-tap chips.
The template
Once the queue could read the real questions, it could also read the fake ones, and it did.
Each of these files begins with a template for filing a new question, so an agent knows the shape. In one repository the template sits inside an HTML comment, which renders as nothing on any page and reads as nothing to any person. The queue does not render. It parses lines, and the lines were there: a heading reading <short title>, a body with <A / B / C with tradeoffs>, and a filing date, which was the day the file was created. Eighty-two days. Oldest thing in the workspace. In another repository the template was indented instead of commented, so it never started a section of its own; it folded into the first live question below it and gave that question a second ask, the placeholder one.
In four repositories, fifteen headings were notes filed inside a parked question: an update, a correction, “option (a) is now void”. The queue had no notion of a parent, so each note became a decision of its own, sorted away from the question it amended. One question’s eight updates rendered as eight rows, and one of those eight carried the section’s only actual ask. In the same week I found six sections whose first body line says, in bold, that they are resolved, still counted as waiting, because the rule for “resolved” only ever read headings and zero headings in thirty files carry that word.
Both directions
Add it up and the count was wrong both ways at once. It hid a hundred and three decisions that existed and showed a template, eight copies of one note and six questions that had answered themselves. Neither error produced a symptom. A queue with thirty-six items looks like a queue. A queue whose oldest item is <short title> looks like a queue with an oddly named item, which I had noticed and not looked at, the way you notice a spelling mistake on a sign.
The fixes are all reading rules. Comments are blanked in place before parsing, same bytes, same line numbers, so nothing that relies on line positions moves. A question mark at the end of a heading makes the heading the ask. A deeper heading under a section with a body of its own is a note and folds into it, above the chips, because a note is usually a correction of the choice. A first body line that says resolved is resolved, unless it says partly.
What the count was for
I had been treating the number at the top of that list as a measurement of my backlog. It was a measurement of how well a parser agreed with thirty files written by hand, by agents, over five months, each in whatever idiom seemed natural at the time. The files were never wrong. Each one is perfectly legible to a person. The queue was reading them with a grammar none of them had agreed to, and every disagreement became either an invisible decision or a phantom one.
The template is gone from the list. Its filing date was the one thing about it the queue had right.