## Summary When a user answers a Duo clarifying question posted in a work item discussion thread, the **work item description** (the spec / source of truth) should be updated to reflect the decision made. Currently, decisions are only captured in: - The flow's checkpoint (temporary, deleted after 30 days via `CHECKPOINT_RETENTION_DAYS`) - The workplan body (durable but unstructured and non-deterministic) This means the work item description — which downstream developers reference for acceptance criteria — can become stale as the refinement flow progresses. Related context: [Initial prototype demo (~8 min mark)](https://gitlab.com/groups/gitlab-org/-/work_items/22703#note_3643420500) and the [current prototype](https://plan-sdd-bdc021.gitlab.io/). Recording decisions as Decision Log entries is tracked separately in https://gitlab.com/gitlab-org/gitlab/-/work_items/608859. This issue covers the complementary update to the description itself. ## Problem The work item description is the human source of truth for a work item. When Duo asks a clarifying question and a user answers it, that decision changes the intent of the work — but today that change is only reflected in the workplan output, not in the description. As the effort moves downstream into development, the description becomes the reference point, and stale content leads to misalignment. ## Open Questions / Design Decisions The following questions were raised in the [discussion thread](https://gitlab.com/groups/gitlab-org/-/work_items/22772#note_3844044320) and need resolution before implementation: **1. When should the description update?** - Immediately upon answering each question (preferred for real-time accuracy and to avoid attribution issues), or - After all questions are answered and the flow resumes (simpler API design, single network round-trip) - Note: if the flow is paused past the 30-day checkpoint threshold and cancelled, answers provided may never result in description updates **2. How does Duo find the right place in the description to update?** - Some questions reference a specific part of the description verbatim; others fill a gap not tied to any existing text - A matcher (frontend or LLM-assisted) is needed to anchor a question to the relevant description section - The floating-card-over-highlighted-text UX from the prototype is a future item, not in scope for now **3. What happens when a user skips a question (defers to Duo)?** - A skip is not an explicit human decision — these Duo-made assumptions should be captured differently, potentially in an "Assumptions" section, and clearly distinguished from user-confirmed decisions - Related discussion: https://gitlab.com/groups/gitlab-org/-/work_items/22773#note_3822867498 **4. Description vs. workplan duplication** - The description should own the **"Why"** and **"What"**; the workplan should own the **"How"** - Until that separation is enforced, some duplication between description and workplan is expected - The workplan currently includes full context so the developer agent doesn't need to fetch the work item separately — this behavior may change in the future **5. Attribution of description changes** - Immediate updates are preferred so changes are attributed to the user who answered the question, not to whoever resumes the flow later - Existing description history/system notes should be leveraged (no new tracking mechanism needed) - Related discussion on timing of decision capture: https://gitlab.com/groups/gitlab-org/-/work_items/22773#note_3833249379 ## Proposed Approach (Happy Path) - When a user selects an answer to a Duo clarifying question, the flow (or a triggered sub-flow) updates the work item description to incorporate the decision - The core technical challenge is finding **anchors** in the description that tie to the asked question, and computing the replacement text following answer selection - Description history should rely on the existing system note diff mechanism already in place for work items ## Out of Scope (for now) - Contextual commenting (floating card over highlighted description text) — future iteration - Non-happy-path handling (e.g., user deletes workplan and regenerates after description was already updated) ## Related - Parent epic: https://gitlab.com/groups/gitlab-org/-/work_items/22772 - Record a Decision when a Duo clarifying question is answered: https://gitlab.com/gitlab-org/gitlab/-/work_items/608859 - Initial prototype discussion (~8 min mark): https://gitlab.com/groups/gitlab-org/-/work_items/22703#note_3643420500 - Current prototype: https://plan-sdd-bdc021.gitlab.io/ - Related decisions discussion (WS-5 epic): https://gitlab.com/groups/gitlab-org/-/work_items/22773#note_3833249379 - Skip/defer discussion: https://gitlab.com/groups/gitlab-org/-/work_items/22773#note_3822867498