v1.34.0 ·
The question nobody could answer
On a fieldmodel-apps piece of work called assertion-store, on 2026-09-26, the product owner declined all four of the first questions AIDLC asked. The reply was the same each time: "I still don't understand what this assignment, sensitive or tenant is."
That was my bug, not theirs. The Question Protocol (packages/content/skills/00-overview.md, "The spec") lists six fields every question carries. None of them asks the agent to say what the thing being decided is. So the agent writes for a reader who already has its vocabulary, and it had just read the schema, the security policy and the design records. Of course every concept looked obvious to it.
The rewrite that fixed it opened with a primer and gave each question a "What it is, functionally" section. It carried one running example through all four questions and defined each option by what someone would see. All four were then answered, three of them against the recommendation.
What changed
Every question now says what the thing being decided is, with one concrete example, before it says why it matters. The spec gets a required seventh field, "What it is", between the decision and why it matters. A file with several questions about one concept opens with a shared primer and reuses one running example, and the example has to show what would really happen. Options are described by what would happen, not by how it would be built.
The prompt carries the same line on every platform. On Claude Code each option's consequence becomes its description word for word, so a consequence written in schema terms made the prompt unreadable even when the file was fine. Those descriptions are now observable effects.
Why this way
I could have made the field required only on hard questions. That sounds proportionate. I rejected it because the agent decides what counts as hard, and the agent is the worst judge of that. A field it may skip gets skipped exactly when it is needed. So the field is always there, and only its length varies. For an everyday idea it is one sentence.
The rule is stated once, with its reason, under ## Every platform in the rendering file, because five copies of one rule are five places to drift. That was not enough. Five of the six platform directives list what a prompt contains: the decision as a bold line, the options, the recommendation. An agent follows the most specific list it has, so a list that omits the explanation beats a shared paragraph that includes it. Each directive now names the line where it lists the prompt's contents. One directive told the agent to keep the prompt to the decision, the option labels and the file path, which would have removed the explanation on the platform with the least room. That sentence now keeps it.
What it does not do
I did not build the obvious follow-on, a check that opens question files and fails when one lacks the new field. It would have caught real misses. It is also one more thing every future piece of work has to pass, and that kind of feature has caused most of our bugfixes. The rule lives where the agent reads it, and the tests pin it there, including one derived from the platform registry so a new platform cannot ship without it.
So whether agents actually follow it is left to real use. That is also where the problem was found. No state format, CLI flag or config key changes, and existing question files stay valid.