Open Questions Protocol

Overview

A genuine product decision the code cannot settle is recorded with record_open_questions, never written into the report as prose and never asked with ask_user — you hold no ask_user tool on an analiz task. The system shows every open question as an answer box above the report; the human answers there, not in chat. The report's risks section (analiz-html-report) is risks only — it never carries open questions.

A question the codebase already answers is not a question. Exhaust codebase_search / grep_code / get_symbol_skeleton / expand_symbol_context and the project's own docs (technical-analysis-workflow) before concluding only the human can settle it.

Recording a question

record_open_questions takes three independent operations in one call:

• questions — up to 10 NEW questions: {prompt, kind: product|technical, blocking, recommended_answer?}. The server assigns the key (Q1, Q2, …) in creation order — never invent one.
• update — edits to questions you already recorded, by key: any of prompt, kind, blocking, recommended_answer. Refused once the question is answered if you try to change its prompt — the human answered that exact wording; withdraw it and add a new one instead of rewriting underneath their answer.
• withdraw — keys an answer or further reading made moot. A withdrawn question stays on the record (status withdrawn) and never blocks anything again.

recommended_answer is required whenever blocking is false — refused otherwise. There is no such thing as a non-blocking question with no answer to proceed on.

The call returns the task's full current list (key, kind, blocking, status, answer) as text — read it to confirm the key a new question got before referencing it later in the same run. list_open_questions returns the same list on demand, with every answer, for a run that did not just write one (a revision, a resumed run).

Blocking vs non-blocking

Default to non-blocking. A reasonable default almost always exists: record it with recommended_answer and keep working. Blocking is the exception, reserved for a question where proceeding on ANY guess would waste the implementation, not merely a question you'd rather not guess at.

	Example
✅ Non-blocking	"Should archived tasks be included in the export?" — kind product, recommended_answer: "No — archived tasks are excluded from every other board export." A wrong guess here costs one column in a CSV, not a redesign.
✅ Non-blocking	"Keep the existing 30-day retention or extend it?" — kind product, recommended_answer: "Keep 30 days — no stated reason to change it."
✅ Blocking	Two incompatible product behaviours with no basis in the code or the brief to choose between them (e.g. "on conflict, does the import overwrite the existing row or skip it?" when both are one-line changes but produce silently different data).
✅ Blocking	An external system or contract you cannot see (e.g. the brief assumes a partner API's rate limit or auth model you have no access to confirm).
✅ Blocking	A scope choice that changes WHICH repositories are touched (e.g. "real-time" meaning push notifications vs. polling — one adds a websocket service, the other doesn't).
❌ Should be non-blocking, not blocking	"What should the CSV column order be?" when nothing in the brief or the code implies an order — pick one, state it, recommend it. Guessing wrong here is a one-line fix later, not a wasted implementation.
❌ Should not be a question at all	"What does TaskRepository.ListByProject return?" — get_symbol_skeleton answers this; escalating it is the Red Flag technical-analysis-workflow already names.

Ending the run on a blocking question

A blocking question does not end the run early. Explore everything else first — the report attaches "as far as it got": summary, context, and as much of design/plan/split as the unanswered question doesn't gate. Then:

1. record_open_questions with the blocking question(s) (and any non-blocking ones you also found).
2. add_task_document (new) or update_task_document (revision) with the partial report.
3. A summary comment stating what's blocked and on what.
4. STOP. The run ending with a pending blocking question parks the task in blocked instead of analiz_review — do not move it yourself either way.

Resuming after an answer

You are re-dispatched with payload {"resumed": "questions_answered", ...} once the human sends answers, or you see new answers in your run context's "Open questions" block on any later run. Either way:

1. list_open_questions if you need the full picture (keys, kinds, every answer) beyond what the context block shows.
2. Continue the report from where it stopped — do not restart it. Revise the SAME document with update_task_document, never a second add_task_document.
3. Withdraw or replace any question an answer made moot (e.g. answering Q1 removes the premise of Q2).
4. Finish the report and present it the normal way (analiz-human-review-gate).

In need_revision and done

Honour every human answer in the revised report, the same way you honour review comments. An unanswered non-blocking question means its recommended_answer stands as written — do not re-ask it, do not treat silence as a rejection.

In done (decomposition, task-decomposition): if a human's answer contradicts the approved split or plan in a way the decomposition cannot absorb without re-deciding the design, do NOT decompose. add_task_comment naming which answer conflicts with which part of the plan, and stop — the human resolves the plan before you split it.

Red Flags

• Writing a question into the report's text, or into a task comment, instead of record_open_questions — the human never sees an answer box for it.
• Calling (or planning to call) ask_user on an analiz task — you do not hold it here.
• A non-blocking question with no recommended_answer — refused; you have not actually decided what to do if nobody answers.
• Marking a question blocking because it is inconvenient to guess, not because every guess would waste the implementation.
• Editing an answered question's prompt with update instead of withdrawing and adding a new one.
• Decomposing in done while a human's answer still contradicts the approved split.
• Re-asking an already-answered question, or treating an unanswered non-blocking question as a rejection of your recommendation.