## Summary As a part of https://gitlab.com/gitlab-org/gitlab/-/work_items/629471, we need a backend API that updates the work item description when a user answers a Duo question. The frontend already resolves the decision of a Duo question when the user resolves its thread. This issue adds a hook to that resolve operation. The hook gets an updated description from the AI gateway and saves it as the user who resolved the thread. ## Problem The work item description is the source of truth for a work item. An answer to a Duo question can change the scope of the work. Today, the answer goes into the Decision log and the workplan only. The description does not change, and it becomes out of date. The current tools do not solve this problem: - A Duo Agent Platform flow is too slow and too large for one small edit. - The `generateDescription` action of the `aiAction` mutation does not save the description. It sends the text through the `aiCompletionResponse` subscription only, and the client must save it. If the user closes the tab, the text is lost. The action is available on GitLab.com only (`self_managed: false`), and it uses a Duo Classic unit primitive. Its prompt writes a new description. It does not edit the current description. - The workplan flow does not write answers into the description. When the flow resumes, `Ai::DuoWorkflows::ResumeWorkplanService` sends only the questions and the answers to the flow. These technical constraints apply: - Only the `workItemDecisionResolve` GraphQL mutation calls `WorkItems::Decisions::ResolveService`. The frontend sends this mutation when a user resolves a Duo question thread on the work item page. If a user resolves the thread in a different way, the decision stays open. - `ResolveService` has no events or callbacks. It changes the decision in a database transaction. GitLab does not let code queue a Sidekiq job in a transaction (`config/initializers/forbid_sidekiq_in_transactions.rb`). - `WorkItems::UpdateService` runs the quick actions that it finds in the description (`WorkItems::WidgetableService#handle_quick_actions`). It also creates to-do items for new mentions. If the model output has a quick action (for example, `/close`) or a mention, GitLab runs it as the user who resolved the thread. - The AI request can take some seconds. During this time, a different user can edit the description. - A user can resolve a Duo question without an answer. This is not a decision by the user, and it must not change the description. - The AI gateway does not accept new prompts in `ai_gateway/prompts/definitions/`. New prompts go in `ai/features/<domain>/<feature>/prompts/`. ## Proposal The frontend does not need a new call. The current `workItemDecisionResolve` mutation starts the update. ### GitLab backend 1. In `WorkItems::Decisions::ResolveService`, publish a new `WorkItems::DecisionResolvedEvent` after the transaction completes. The event data is the decision ID, the work item ID, and the user ID. Publish the event only when these conditions are true: - The decision has a `workflow_id`. This shows that a Duo question created the decision (`WorkItems::Decisions::CreateFromDuoQuestionService`). The `source` column from https://gitlab.com/gitlab-org/gitlab/-/work_items/629206 will replace this check. - The decision has a selected option or a written-in answer. 1. Add a Sidekiq worker that subscribes to the event (`Gitlab::EventStore::Subscriber`, `idempotent!`). The worker does these steps: 1. Load the decision, the work item, and the user. Stop if the user does not have the `update_work_item` permission. Stop if `Ai::DuoAgentPlatform.available?(user:, container:)` is false. 1. Record the `lock_version` of the work item. 1. Send one request to the AI gateway. Use a new `Gitlab::Llm::AiGateway::Completions` class with the `duo_agent_platform` unit primitive. Use the same pattern as `Ai::DuoWorkflows::GenerateWorkflowTitleService`. The inputs are the title, the current description, the question, the options, the selected answer, and the rationale. 1. Make sure that GitLab does not run quick actions from the result. 1. Save the result with `WorkItems::UpdateService` as the user, with the recorded `lock_version`. Use the same pattern as `WorkItems::TaskListReferenceReplacementService`. If an `ActiveRecord::StaleObjectError` occurs, do steps 2 to 5 again one time. If the error occurs again, stop. 1. GitLab then creates these items with no new code: a `DescriptionVersion`, the system note with the diff, `last_edited_by`, and the `issuable_description_updated` and `workItemUpdated` subscription events. 1. Add a `description_version_id` column to `work_item_decisions`, with a foreign key to `description_versions` (`ON DELETE SET NULL`). The worker writes `work_item.saved_description_version` to this column. Show the column on the `WorkItemDecision` GraphQL type as a `descriptionVersion` field of type `DescriptionVersionType`. The frontend uses this field to show the diff for each decision on its question card. This diff does not merge with other changes, because the activity feed merges only the system notes. ### AI gateway (`ai-assist`) Do these changes in a separate MR: - Add a prompt in `ai/features/<domain>/<feature>/prompts/base/1.0.0.yml` with `unit_primitive: duo_agent_platform`. - The prompt returns the full description. It changes only the parts that the decision affects, and it keeps all other text the same. It does not add mentions or quick actions. The workplan flow `1.2.0` has similar rules for description edits, and the new prompt can use them. - Add the prompt ID to `PROMPT_ID_TO_FEATURE_SETTING` in `ai_gateway/prompts/registry.py`, with the `duo_agent_platform` feature setting. If the prompt ID is not in this map, self-managed instances fail with an "Invalid feature setting" error. ### Out of scope - Changes to the description for a question that the user resolved without an answer. - A link from a question to one part of the description. - A status (`pending`, `done`, `failed`) on the decision. For MVC, the frontend shows "Updating description" after the user resolves the thread. It removes the status when the `issuable_description_updated` subscription sends an event, or after a timeout. ### Dependencies - The `decision_log` feature flag. - https://gitlab.com/gitlab-org/gitlab/-/work_items/608859 --- _This issue was drafted with :claude: and follows [ASD-STE100](https://www.asd-ste100.org/)._