Skip to content

v1.34.0 ·

The question nobody could answer

The problem

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.

On fieldmodel-apps assertion-store (2026-09-26) the product owner declined all four first-asking requirements questions with "I still don't understand what this assignment, sensitive or tenant is". The rewrite that fixed it opened with a primer, gave each question a "What it is, functionally" section, carried one running example through all four, and defined each option by what someone would see. All four were then answered, three against the recommendation.

The prompt has the same gap. On Claude Code each option's consequence becomes its description verbatim, so a consequence written in schema terms makes the prompt unreadable even when the file is fine.

How it could be solved

Three decisions, and each one turned on the same fact: the agent writing the question is the worst judge of whether the question needs explaining.

The first was whether the new field should be required on every question or only on the hard ones. Required only where the concept is unfamiliar sounds proportionate, and it would have kept short questions short. It was rejected because of who decides what counts as unfamiliar. The agent had just read the schema, the security policy and the design records, so to the agent every concept in those questions was obvious. That is exactly how four questions went out that the person answering could not follow. A field the agent may skip gets skipped precisely when it is needed. So the field is always there, and only its length varies: for an everyday idea it is one sentence.

The second was where to state the rule. The emitted rendering file already states one rule for every platform in a single place, on the reasoning that five copies of one rule are five places for it to drift. The same treatment was the obvious choice here. It was not enough on its own. Five of the six platform directives spell out what a prompt contains, in order: the decision as a bold line, then the options, then the recommendation. An agent follows the most specific list it has, and a list that leaves the explanation out would win over a shared paragraph that puts it in. So the rule is stated once, with its reason, and every directive also names the line at the point where it lists the prompt's contents. One platform's directive went further than the rest: it 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.

The third was what to leave out. The obvious follow-on is a check that opens question files and fails when one lacks the new field. It would have been easy to write and would have caught real misses. It was not built. A check that inspects lifecycle files is one more thing every future piece of work has to pass, and on this project that kind of feature has caused most of the bugfixes. The rule lives where the agent reads it, in the protocol and in the rendering, and the tests pin it there, including one derived from the platform registry so a new platform cannot ship without it. Whether agents actually follow it is left to real use, which is also where the problem was found.

How AIDLC solves it

Every question AIDLC asks now says what the thing being decided is, with one concrete example, before it says why it matters. Options are described by what would happen, not by how it would be built.

  • The spec gains a required seventh field, What it is, between the decision and why it matters. A file with several questions on one concept opens with a shared primer and reuses one running example. The example must show what would really happen.
  • The prompt carries the same line on every platform. The rendering file states it once under ## Every platform; each of the six directives names it where it lists the prompt's contents. Claude Code's option descriptions become observable effects.
  • The constitution skill's worked example follows the new shape.

No state format, CLI flag or config key changes. Existing question files stay valid.