## Summary The workplan widget shows the readiness score today, but the score alone does not tell a user *why* it is what it is or what to change to raise it. The backend now persists and exposes the accompanying markdown feedback (`readinessScoreFeedback`), so this issue tracks the **frontend** work to surface that feedback in a panel next to the score. > **Scope:** Frontend only. The backend field and GraphQL read path already shipped (see references). ## Parent epic [WS-6: Work Item Readiness Score &23050](https://gitlab.com/groups/gitlab-org/-/work_items/23050) ## Design - Figma: https://www.figma.com/design/uJb85wjoRaj7MMvjxAmdHf/SDD-Iteration-Path?node-id=686-55641&t=gnBPPNGPTsNS6WQ3-1 - Prototype: https://plan-sdd-bdc021.gitlab.io/ Follow the Figma frames for placement, spacing, and the empty/collapsed treatment. Flag any deviation from the current `WorkItemConfidenceScore` layout with the designer before implementing. ## Current state - `ee/app/assets/javascripts/work_items/components/ai_widget/work_item_confidence_score.vue` renders the score as a level (Low / Medium / High) plus `ConfidenceBar`, with the raw `Score: X / 100` value tucked inside a `HelpPopover` title. - Thresholds live in `ee/app/assets/javascripts/work_items/components/ai_widget/constants.js` (`CONFIDENCE_SCORE_MEDIUM_THRESHOLD`, `CONFIDENCE_SCORE_HIGH_THRESHOLD`, `PLAN_CONFIDENCE_LEVELS`). - The score is fetched through `ee/app/assets/javascripts/work_items/graphql/work_item_agent_plan.fragment.graphql`, gated by the `$includeReadinessScore` variable: ```graphql fragment WorkItemAgentPlanFragment on WorkItemWidgetAgentPlan { type content aiPlanningEnabled readinessScore @include(if: $includeReadinessScore) } ``` - Everything is behind the `workplan_score` feature flag. ## GraphQL reference The read path is exposed on `WorkItemWidgetAgentPlan` and gated on the same `workplan_score` flag. See [!252884](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/252884) for the field definition and manual verification steps. ```graphql query { workItem(id: "gid://gitlab/WorkItem/1") { widgets { ... on WorkItemWidgetAgentPlan { readinessScore readinessScoreFeedback } } } } ``` Important constraints from that MR: - `readinessScoreFeedback` is **raw markdown** and nullable. Per the decision in [#617982](https://gitlab.com/gitlab-org/gitlab/-/work_items/617982), `readinessScoreFeedbackHtml` is not the intended frontend contract, so the panel renders the markdown client-side. - The field carries `FieldCallCount, limit: 1`, so it **can only be requested for one work item at a time**. It must not be added to any list query, only to the single work item agent plan query. - Resolving the field triggers an object storage read, so it must be requested only when the flag is on and the panel is actually shown. Reuse the existing `$includeReadinessScore` gating variable rather than adding an unconditional field. - Both fields live in the same object storage blob as `content`, so requesting them together on one work item costs a single fetch. ## Frontend work 1. **Extend the query** - Add `readinessScoreFeedback` to `work_item_agent_plan.fragment.graphql` under the existing `@include(if: $includeReadinessScore)` gate. - Verify the cache helpers in `ee/app/assets/javascripts/work_items/graphql/agent_plan_cache_utils.js` keep working with the added field, including the `includeReadinessScore: false` path. 2. **Replace the info popover with a toggle button** - Remove the existing `HelpPopover` (info icon + tooltip) from the score component. - Replace it with a `tertiary` button with a tooltip of **"Score details"**. - The button acts as a toggle: clicking it opens the feedback panel; clicking again closes it. - Update the button's position to match the new location shown in the Figma design (the info icon was previously positioned differently from the Figma spec — implement the Figma location). 3. **Build the feedback panel** - Add a component (e.g. `readiness_score_feedback.vue`) alongside `work_item_confidence_score.vue` that renders the feedback markdown per the Figma design. - The panel contains the score feedback markdown, a brief explanation of the score, and a link to docs. - Render the markdown safely. Do not inject raw HTML; use the established markdown rendering path used elsewhere in the work item widgets. - Keep the score indicator and the feedback panel visually connected, matching the design. 4. **Handle non-happy paths** - `null` or empty feedback: render nothing (no empty panel, no placeholder copy unless the design specifies one). - Loading: no layout shift while the agent plan query is in flight. - Query error: fail quietly for the panel; do not break the rest of the workplan widget. Error surfacing is tracked separately in [#628571](https://gitlab.com/gitlab-org/gitlab/-/work_items/628571). - Feedback present but score `null`: still safe to render, since the score already normalizes `null` to `0`. 5. **Feature flag and i18n** - Keep the panel behind `workplan_score`, consistent with the score UI. - All user-facing strings use the `AgentPlan|` namespace, matching the existing components. 6. **Tests** - Component spec for the panel: feedback present, `null`, empty string, and markdown rendering. - Update `ee/spec/frontend/work_items/components/ai_widget/work_plan_spec.js` and the `buildAgentPlanWidgetMock` helper in `ee/spec/frontend/work_items/mock_data.js` to carry `readinessScoreFeedback`. - Update the MSW handlers in `ee/spec/frontend/msw_integration/work_items/handlers.js` so the integration variants can exercise the panel. - Assert the field is not requested when `includeReadinessScore` is `false`. ## Acceptance criteria - [ ] The workplan widget renders the readiness score feedback from `readinessScoreFeedback`, matching the Figma design. - [ ] The existing info popover is replaced by a `tertiary` toggle button with tooltip "Score details" that opens/closes the feedback panel. - [ ] The toggle button is positioned per the updated Figma design. - [ ] Markdown feedback renders correctly and safely. - [ ] The field is requested only for a single work item and only when `includeReadinessScore` is true, so no extra object storage reads or N+1 are introduced. - [ ] `null` / empty feedback renders nothing; loading and error paths degrade gracefully. - [ ] The panel stays behind the `workplan_score` feature flag. - [ ] Frontend specs, mock data, and MSW handlers updated. ## References - GraphQL read path: [!252884](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/252884) - Backend model field: [!252883](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/252883) - Backend issue: [#617982](https://gitlab.com/gitlab-org/gitlab/-/work_items/617982) - Score frontend wiring: [#608260](https://gitlab.com/gitlab-org/gitlab/-/work_items/608260) - Scoring methodology: [#613998](https://gitlab.com/gitlab-org/gitlab/-/work_items/613998) - Feature flag rollout: [#607899](https://gitlab.com/gitlab-org/gitlab/-/work_items/607899)