## Summary The work plan readiness score currently persists only the numeric value (`readiness_score` on `work_item_agent_plans`, added in [#611320](https://gitlab.com/gitlab-org/gitlab/-/work_items/611320) via [!249416](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249416) and exposed as `readinessScore` in [!249498](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249498)). We also need to persist and expose the **feedback that accompanies the score** so the UI can tell the user why the score is what it is and what to address to raise it. Parent epic: [&23050](https://gitlab.com/groups/gitlab-org/-/work_items/23050) ## Context - The score stays attached to the work plan table and widget, per [this decision](https://gitlab.com/groups/gitlab-org/-/work_items/23050#note_3675705170). - The scoring methodology that produces this feedback is tracked in [#613998](https://gitlab.com/gitlab-org/gitlab/-/work_items/613998). - The feedback is markdown of unbounded size, so it does not belong in a Postgres column. It goes to object storage instead, per [this discussion](https://gitlab.com/gitlab-org/gitlab/-/work_items/617982#note_3766396239). ## Decisions - Write path: settable via the `workItemUpdate` mutation, flag-gated like `readiness_score`. - `readinessScoreFeedbackHtml` not exposed; raw markdown is sufficient for the frontend. - `FieldCallCount, limit: 1` on the read field, matching `content`. - Staleness handling deferred to a follow-up. ## Proposal Store `readiness_score_feedback` in object storage rather than in a database column, reusing the same external-storage mechanism (and bucket) that already holds the work plan `content`, and expose it as `readinessScoreFeedback` on `WorkItemWidgetAgentPlan`. `WorkItems::AgentPlan` already wires this up in `ee/app/models/work_items/agent_plan.rb`: ```ruby cache_markdown_field :content, storage: :external, issuable_reference_expansion_enabled: true self.external_storage_uploader_class = ::WorkItems::AgentPlanContentUploader ``` Confirmed: `cache_markdown_field :x, storage: :external` registers both `x` and `x_html` as virtual attributes via `externally_stored_field`, and `build_external_payload` writes all registered fields into one blob whose name is deterministic (`#{work_item_id}.json`). **No migration, no `_html` column, and no file-name column are required.** Existing blobs that predate the field read back as `nil`, so no backfill is needed. Naming rationale: the `readiness_score_` prefix keeps the pair discoverable and moves together if the score ever relocates off the work plan table. `feedback` reflects that the content is actionable (what to address), not a justification of the number. ## Scope - [ ] Add `readiness_score_feedback` as an externally stored markdown field on `WorkItems::AgentPlan` via `cache_markdown_field ..., storage: :external`, sharing `WorkItems::AgentPlanContentUploader` - [ ] Assert in specs that the feedback serializes into the same object storage JSON blob as `content` - [ ] Model validation on `WorkItems::AgentPlan` (`allow_nil: true`; length limit consistent with `CONTENT_LENGTH_MAX`) - [ ] Expose `readinessScoreFeedback` on `WorkItemWidgetAgentPlan`, gated on the existing `workplan_score` feature flag, matching the scopes used by `readinessScore` (`[:api, :read_api, :ai_workflows]`) - [ ] Watch for N+1 / extra object storage reads: resolving the field triggers a blob read, so it must not be fetched when the flag is off or the field is not requested - [ ] Allow the score generation flow to write the feedback together with the score - [ ] Update GraphQL schema docs (`bundle exec rake gitlab:graphql:compile_docs`) - [ ] Specs: model (external persistence and read-back, validation boundaries, nil case), type spec, request spec (value present, nil, flag on/off) ## Follow-ups - Handle staleness: clear or refresh the feedback when the plan is regenerated or edited, so it never contradicts the current score. ## Risks and dependencies - The external storage mechanism may change. Today a record gives no way to know whether a blob exists without attempting the read; see [#616229 (comment)](https://gitlab.com/gitlab-org/gitlab/-/work_items/616229#note_3694614696) and [!249644](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/249644). Coordinate before landing so this work does not need reworking. ## Related - Score backend field: [#611320](https://gitlab.com/gitlab-org/gitlab/-/work_items/611320) - Scoring methodology: [#613998](https://gitlab.com/gitlab-org/gitlab/-/work_items/613998) - Frontend wiring: [#608260](https://gitlab.com/gitlab-org/gitlab/-/work_items/608260) - Feature flag: [#607899](https://gitlab.com/gitlab-org/gitlab/-/work_items/607899) - External storage existence tracking: [#616229](https://gitlab.com/gitlab-org/gitlab/-/work_items/616229)