open-questions-protocol
Use when an analiz question needs the human, not the code, to decide - recording it with record_open_questions, judging blocking vs non-blocking, and resuming the report after an answer
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- open-questions-protocol
- category
- architecture
- description
- Use when an analiz question needs the human, not the code, to decide - recording it with record_open_questions, judging blocking vs non-blocking, and resuming the report after an answer
03 SKILL.md 正文
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, bykey: any ofprompt,kind,blocking,recommended_answer. Refused once the question is answered if you try to change itsprompt— 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 (statuswithdrawn) 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:
record_open_questionswith the blocking question(s) (and any non-blocking ones you also found).add_task_document(new) orupdate_task_document(revision) with the partial report.- A summary comment stating what's blocked and on what.
- STOP. The run ending with a pending blocking question parks the task in
blockedinstead ofanaliz_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:
list_open_questionsif you need the full picture (keys, kinds, every answer) beyond what the context block shows.- Continue the report from where it stopped — do not restart it. Revise the SAME document with
update_task_document, never a secondadd_task_document. - Withdraw or replace any question an answer made moot (e.g. answering Q1 removes the premise of Q2).
- 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_useron 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
promptwithupdateinstead of withdrawing and adding a new one. - Decomposing in
donewhile 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.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns