engineering-memory 1.11.11 → 1.11.12

package/skill/references/questionnaires.md

@@ -6,7 +6,11 @@ Use the host's native questionnaire for every question to the user, including im
 
 Use `questionnaire.ask` for a required decision. It records the question before opening a native MCP form. Use a stable question identifier belonging to the current task and decision, so a retry returns to the same question instead of creating another one. A new decision needs its own identifier; an answer to an earlier proposal, branch or delivery does not approve a later one.
 
-Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
+Pass `repoRoot`, `questionnaireId`, `message` and two to twelve `options`, each with an `id` and `label`. Identifiers use letters, digits, underscores or hyphens.
+
+A question has to be answerable by someone who has not followed the work. Say in `context` why it is being asked, give in `example` one concrete thing the decision changes, and give every option a `description` of what happens next if it is chosen. Show a record, a branch or a project by its title or name; an identifier or a hash in the visible text is refused, and one that really has to be shown goes inside backticks. Write all of it in the language the user is writing in and pass that language as `language`, a BCP-47 tag such as `tr`, `en` or `pt-BR`. The tag is remembered for the account and the computer, so it is asked for once: `session.entry` and every tool that opens a form take the same argument, and `questionnaire.ask` is refused while no language is known.
+
+Every form carries one more choice, "I did not understand; explain in more detail first". It is never recorded as an answer. When a call returns `needs_explanation`, explain in chat why the question is asked, what each option leads to and one example, then show the same question again with `questionnaire.resume`. A free-text reply that says the question was not understood is handled the same way and is not passed on as the decision. Set `allowFreeText` only when the user needs to give an answer outside those options. `questionnaire.resume` takes the same `repoRoot` and `questionnaireId`. These tools collect decisions; they do not commit, publish, bind a project or perform the selected action. Apply the accepted answer through the relevant lifecycle tool, checking the current target and version first.
 
 Fixed-choice answers can be replayed from the local receipt. Free text is returned only in the accepting call and is never stored. If a later receipt says the answer is unavailable, recover it from the user's actual answer in the conversation; never reconstruct it from the options. If it cannot be recovered, explain that it must be requested again using a new question identifier.
 
@@ -324,8 +328,9 @@ Saving a profile does not authorize filesystem initialization.
 ## Inspection confirmation language
 
 For memory.sync_start, pass language: tr in a Turkish conversation and language: en in an English
-conversation. Use the conversation language, never the computer locale. Legacy calls without language
-use English. The form shows a short source reference, scope, the treatment of uncommitted changes and
+conversation. Use the conversation language, never the computer locale. A call without language uses
+the language remembered from an earlier call, and English when none is known. The bridge's own forms
+have Turkish and English text; any other language opens them in English. The form shows a short source reference, scope, the treatment of uncommitted changes and
 the separate approval needed for permanent memory. Full commit and request hashes stay in the durable
 approval binding, not in the visible question. Generic questionnaire.ask messages and option labels
 are written by the agent in the same language; pass language for the native help and field labels.