Human in the loop

Read more about SDD in Spec-Driven Development.

Maturity: Still defining

Summary

When the async workplan flow hits a decision it should not make alone, it asks a clarifying question in the work item discussions. A human answers there, and the flow picks up the answer and continues. Examples are whether something is free or paid, who can see it, or whether a change breaks existing behavior. A plan built on a wrong guess is worse than no plan.

Epic: WS-4: HITL and notifications

Designs: SDD iteration path in Figma

Why work item discussions

• A question in a discussion is durable. A chat session is not.
• Other people can see the question and weigh in.
• The work item already holds everything else about the work, so the decision sits next to what it affects.
• Any flow that needs to ask something can use the same surface, not only workplan generation.

Interaction

1. The flow posts a comment with its question and attaches a small machine-readable payload that describes the question, the options, and its recommendation.
2. The work item renders the question as a card in the thread. The card shows up to five options and which one the flow recommends. Cards render only for notes authored by the Duo bot.
3. A user answers by choosing an option. Some questions accept more than one answer. A user can also give a free-text answer.
4. If none of the options are right, a user can reject them. An explanation is required, because that is what the flow acts on next.
5. Answering posts the choice as an ordinary reply and resolves the thread. The thread is resolved only if the user has permission to resolve it. The chosen answers remain visible; options that were not selected can be expanded in a disabled state after resolution (merge request 260428).
6. The user selects Continue on the Implementation widget to resume the flow with the answers and open the session in the Duo drawer.

Permission to resume and eligibility to supply answers are separate. The resume service checks work-item update permission and project remote-flow availability, then uses the original flow owner’s identity. Starting a new CI flow has a separate Developer-level permission check; aligning the role policy is tracked in issue 634208. The resume service includes replies only from users with a project role above Guest. Replies from Guest and lower roles are excluded, even when the author can update the work item and select Continue.

Thread resolution is not required to resume. The service collects eligible replies to question payloads from both resolved and unresolved threads. Unanswered questions do not block a resume; if there are no eligible replies, the flow is instructed to continue with its best assumptions. A request to expand the description follows a separate path: the user edits the description, and Continue resumes research with the original goal.

Because the answer is a normal comment and a normal thread resolution, everything stays visible. The payload is stripped from note emails.

Question navigation

While a flow awaits input, the Implementation widget shows its open-question count and previous/next navigation. The sticky header also exposes question navigation. Resolved threads are skipped, and answering from a card refreshes the widget without waiting for its next poll (issue 608855, issue 628347, and issue 631032).

The backend counts unresolved flow-note threads across all runs, while navigation filters for question payloads. Progress notes and context requests can therefore inflate the count. A Guest can also resolve a thread whose reply is excluded from the resume goal. The counter is a navigation aid, not an authorization check or a prerequisite for resuming.

Notifications

When the flow pauses for input, the user is notified. This was implemented in the AI Gateway in merge request 6711.

Relationship to the decision log

Automatic recording of clarifying questions and their answers in the decision log is implemented in two parts:

1. The backend creates an open decision with the question, options, and discussion ID when the flow posts a clarifying question (issue 630439).
2. The frontend resolves that decision when the thread is resolved through the work item UI, recording the selected options or free-text rationale and linking the answer reply (merge request 259195).

This integration requires the decision log to be available for the work item’s license and type. If no matching decision exists, such as for an older question, the frontend skips recording. Resolving without an answer records a fixed rationale rather than selecting an option. Reopening and resolving the thread again does not replace the first decision resolution. Resolving a thread outside this UI does not automatically resolve its decision.

Open decisions are stored but hidden from the decision-log panel until resolved. Recording a decision is separate from resuming the flow: Continue does not resolve threads or decisions, and a decision-log mutation failure does not prevent the answer from being posted.

Open questions

• Approval requests: A single run can produce real questions and requests to approve a tool call. The current thinking is that discussions carry questions only, and approvals stay where the person running the flow can see them.
• Updating the spec: Automatically updating the description from a resolved Duo decision is in development (issue 633224). The proposed backend event and worker apply an AI-generated edit and link its description version to the decision. The frontend diff presentation and whether manual decisions should also update the description remain under discussion in issue 629471.
• Unanswered questions: The flow waits for an explicit Continue action, which can resume it without answers. Nothing chases an unanswered question or cleans it up.
• Resolving without replies: The flow currently posts plain comments, which become resolvable threads after a reply. Posting discussions directly is tracked in issue 633575. This is a prerequisite for Resolve all questions.
• Answer eligibility: Aligning resolved-question counts with the resume service’s reply permissions (issue 631546).

View page source - Edit this page - please contribute.