## Questions to answer 1. Should top/primary/secondary categorization label block MR creation, or default to secondary? 2. Should tier label (Free, Premium, Ultimate) block MR creation, or infer it, or default to Free? > **Current answer for both: blocking.** The categorization and tier labels are required before MR creation. Defaulting risks miscategorizing features or exposing tier-restricted features incorrectly. These remain open for PM feedback. ## Existing functionality When the release posts were in the `www-gitlab-com` repository, a regularly scheduled pipeline job would create new release post items from epics/issues. <details> <summary>www-gitlab-com code: how it works</summary> Right now, a script exists to take information from epics and issues and generate yaml files. We don't want to do this exact thing, but it's a pointer to the information we'll need. Description here: https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#release-post-item-generator Note: This doesn't work for confidential issues. You can view details of [the existing job in the www-gitlab-com repo](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab-ci.yml?ref_type=heads#L252). [The script starts here](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/bin/release-post-item?ref_type=heads) ### What the generate-release-post-items CI job does The generate-release-post-items CI job is a scheduled automation that creates release post items from GitLab issues and epics. It runs when the RELEASE_POST_ITEM environment variable is set to "true" in a scheduled pipeline.The job searches for issues and epics in the gitlab-org group (ID: 9970) that have specific release post item labels: - gitlab-org/technical-writing/docs-gitlab-com~15683841 - gitlab-org/technical-writing/docs-gitlab-com~15705741 - gitlab-org/technical-writing/docs-gitlab-com~15705742 [Link to see all current issues & epics with those labels here](https://gitlab.com/groups/gitlab-org/-/work_items?sort=created_date&state=all&or%5Blabel_name%5D%5B%5D=release%20post%20item%3A%3Atop&or%5Blabel_name%5D%5B%5D=release%20post%20item%3A%3Asecondary&or%5Blabel_name%5D%5B%5D=release%20post%20item%3A%3Aprimary&first_page_size=20) For each matching issue/epic, it automatically: 1. Extracts content from the issue/epic including title, description, assignees, milestone, and associated image 2. Creates a YAML file in data/release_posts/unreleased/ with structured release post content 3. Downloads and saves images to source/images/unreleased/ if the issue has an attached image 4. Creates a merge request with the generated content using the Release Post Item template 5. Updates the original issue/epic by adding the gitlab-org/technical-writing/docs-gitlab-com~15683846 label </details> ## Background A "Release notes writer" agent already exists (see [#14546 (closed)](https://gitlab.com/gitlab-com/Product/-/work_items/14546)) and is deployed via the [Agents and Flows group](https://gitlab.com/groups/components/agents-and-flows). The agent project lives at [`components/agents-and-flows/release-notes-writer`](https://gitlab.com/components/agents-and-flows/release-notes-writer). This issue covers the **next two pieces** of the workflow, both added to the same `release-notes-writer` project: 1. **MR creation** — extend the existing agent's system prompt so it can create the release notes MR on the PM's behalf. 2. **Automatic triggering via Flow** — add a Flow to the same project that automatically invokes the agent when the service account is at-mentioned on a work item. > **Note:** There will no longer be any automation in `www-gitlab-com`. The MR will be created in `gitlab-org/gitlab` using the [Release Notes Item MR template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Release%20Notes%20Item.md). > **Note on Flow vs. chat:** The at-mention-triggered behavior described in this issue applies to the **Flow** only. When the agent is invoked directly via Duo Chat, all interaction happens in the chat — the agent does not post work item comments unless explicitly asked. ## Requirements It should live in the existing [`components/agents-and-flows/release-notes-writer`](https://gitlab.com/components/agents-and-flows/release-notes-writer) project. Instead of creating a new agent, both phases are handled by **extending the existing agent's system prompt** and adding a **Flow** to the same project. ### Agent update/verification The following should be verified is already in the current agent, otherwise, it needs to be added to the agent for the release notes content: - Make it clear whether the feature is new or an improvement to an existing feature. - Ensure all links have meaningful text for SEO (for example, use descriptive links instead of "click here"). - Ensure that the text is fewer than 125 words. ### How triggering works The Flow is triggered when the service account is at-mentioned in a comment on a work item (such as epic or issue). The PM includes a keyword in the mention to indicate which action they want: - `@ai-release-notes-writer-gitlab-org help` → replies with a summary of available commands and their syntax - `@ai-release-notes-writer-gitlab-org draft` (or `redraft`) → triggers the draft phase only - `@ai-release-notes-writer-gitlab-org create MR` (or `update MR`, `ready`) → drafts if needed, validates, and creates/updates the MR in one pass - `@ai-release-notes-writer-gitlab-org sync` → syncs the latest release notes from the MR to the work item description **All command keywords are case-insensitive** (e.g., `Draft`, `DRAFT`, `Create MR`, `create mr` all work the same way). The service account is created automatically when the flow is enabled in the `gitlab-org` group, following the naming convention `ai-<flow>-<group>`. The agent reads the triggering comment to determine which mode to run in, and always replies to the person who mentioned it. Since triggering requires a deliberate at-mention, there is no risk of the Flow re-triggering unintentionally on the same work item. ### Work item context By default, the agent operates on the work item where the at-mention comment was posted. The PM can also provide a link to a different work item in their comment (e.g., `@ai-release-notes-writer-gitlab-org create MR https://gitlab.com/gitlab-org/gitlab/-/issues/456`), and the agent will use that work item instead. If the agent is invoked via Duo Chat without a work item context and no link is provided, the agent should ask the PM to provide a link to the work item. ### Triggering from a MR The PM can also trigger the agent from a MR comment. In this case, the agent looks up the related work item using the following priority order: 1. **PM-provided work item link** in the comment 2. **Work item URL in the MR diff content** (the committed release notes file) 3. **Work item URL in the MR description** (e.g., the Feature Issue link) If no work item can be found, the agent replies asking the PM to provide a link. ### Help command (`@ai-release-notes-writer-gitlab-org help`) When the PM mentions the agent with `help` (or with no recognized keyword), the agent replies with a brief summary of available commands: - **`draft`** (or **`redraft`**) — Drafts or refreshes the `## Release notes` section in the work item description. Does not create an MR. - **`create MR`** (or **`update MR`**, **`ready`**) — Validates required labels, drafts release notes if missing, and creates or updates the release notes MR. This is the primary command for most PMs. - **`sync`** — Syncs the release notes from the MR back to the work item description (MR is the source of truth). - **`help`** — Shows this command summary. The reply should also include a link to any relevant documentation or the agent project README for more details. ### Draft phase (`@ai-release-notes-writer-gitlab-org draft` or `redraft`) There is no blocking validation at this stage. Both `draft` and `redraft` trigger the same behavior: - **If no `## Release notes` section exists**: the agent drafts one and updates the work item description, then replies to the mentioner with a comment confirming the section was added. If there are any discrepancies or missing info, these are included in the same reply. - **If a `## Release notes` section already exists**: the agent compares its suggested draft against the existing section. **If there are significant differences** (e.g., missing key details, factual inaccuracies, or substantial content gaps), the agent updates the description with the improved version and replies to the mentioner explaining what changed and why. **If the existing section is already in good shape** (minor or no differences), the agent does **not** update the description. Instead, it replies to the mentioner confirming the section looks good, and includes any minor suggestions or discrepancy notes if applicable. ### MR creation/update phase (`@ai-release-notes-writer-gitlab-org create MR` or `update MR` or `ready`) The `create MR` command (with `update MR` and `ready` as aliases) is the primary command for most PMs. It combines drafting and MR creation into a single pass, producing **one consolidated reply** at the end. **Step 1: Ensure `## Release notes` section exists** If no `## Release notes` section exists, the agent runs the full draft process first (same as `draft`) and updates the work item description. It does **not** stop or post a separate comment for the draft step; it continues to the next step. **Step 2: Check for blocking issues** - `release post item::` categorization label (`::primary`, `::secondary`, or `::top`) — required - At least one tier label (`GitLab Free`, `GitLab Premium`, or `GitLab Ultimate`) — required - At least one platform label (`platform: dedicated`, `platform: GitLab.com`, `platform: self-managed`, `platform: dedicated for gov`) — required **If any blocking issues are found:** the agent replies to the mentioner with **one comment** that includes: - What it accomplished (e.g., "I drafted the `## Release notes` section" if it ran the draft step) - The list of missing labels - **Suggested quick action(s)** the PM can copy-paste to apply them (e.g., `/label ~"release post item::primary"`, `/label ~"GitLab Free"`, `/label ~"platform: self-managed"`). If the agent can infer the correct label from context (e.g., the work item description mentions "Ultimate only"), it should recommend the specific label. - A suggested revision for the release notes prose, if applicable The PM addresses the gaps and re-mentions with `create MR`. **Step 3: Create or update the MR** If all required info is present, the agent runs [MR detection](#mr-detection): - **No existing MR detected:** the agent searches for a docs link if one is not already in the `## Release notes` section (using `gitlab_documentation_search`), creates the MR, and replies with **one comment** containing the MR link, any non-blocking warnings, and the source-of-truth handoff message. - **Existing MR detected:** the agent compares the work item's last updated timestamp against the latest commit timestamp on the MR: - **Work item is newer:** the agent creates a new commit on the existing MR's source branch with regenerated content from the current `## Release notes` section, then replies with the MR link and a note that it was updated, plus the source-of-truth handoff message. - **MR is newer:** the agent replies with a warning: ``"The latest commit on !123 (committed <timestamp>) is newer than the last update to this work item's description (<timestamp>). Are you sure you want to overwrite the MR with the work item's `## Release notes` section? If so, re-run `create MR` with `--force` (e.g., `@ai-release-notes-writer-gitlab-org create MR --force`)."`` The agent does **not** update the MR unless the PM confirms with `--force`. **Non-blocking warnings** (included in the reply but do not block MR creation): - No image in the `## Release notes` section for top/primary items — agent reminds the PM to add one - **Docs link:** if no docs link is present in the `## Release notes` section, the agent searches for the best matching docs page (using the same `gitlab_documentation_search` approach as when drafting) and includes it when creating the MR. Agent mentions it did this. ### MR creation details When the agent creates a new MR, it must: - When creating the commit, follow the formatting as outlined in `doc/development/documentation/release_notes.md#how-to-add-a-feature-release-note` in `gitlab-org/gitlab`, shorten title to 7 words not including articles or prepositions if necessary, ensure all links to `docs.gitlab.com` content are relative URLs, and that at least one category is included using the list from https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/categories.yml (the category can be inferred from the work item `Category:` label if present). - Create the MR in `gitlab-org/gitlab` using the [Release Notes Item MR template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Release%20Notes%20Item.md) - Fill in the **Feature Issue** link under the `## Links` section with the work item URL, so the MR is linked as a related item - Apply the matching `release post item::`, `section::`, `devops::`, `group::` label (plus `~"release post"`, `~"release post item"`, `~"Technical Writing"`, `~"type::maintenance"`, `~"maintenance::refactor"`, from the template) - Apply the matching `platform:` labels from the work item - Assign to the mentioner - When replying to the mentioner about the MR being created, remind them to update the `categories.yml` and `features.yml` files in the `www-gitlab-com` repository, which is required for a top/primary item, optional for secondary. ### Source of truth handoff - **Before MR creation:** the `## Release notes` section in the issue/epic description is the canonical source. The PM edits it directly. - **After MR creation:** the MR (specifically the committed `.md` file) becomes the canonical source. The PM edits the MR directly. When the agent creates or updates an MR, it must: 1. **Reply with the handoff message:** *"The MR is now the source of truth for this release note. To make changes, edit the MR directly. If you need to regenerate from the issue description, use `create MR` again. To sync the MR content back to the issue, use `sync`."* 2. **Add a visible note in the work item's `## Release notes` section** linking to the MR, so anyone reading the issue knows the canonical source has moved. For example, append: `> **Note:** The source of truth for this release note has moved to !123. Edit the MR directly to make changes.` ### MR detection The agent uses a **three-step matching process**, in priority order: 1. **PM-provided MR link** — If the PM includes a MR URL in their comment (e.g., `@ai-release-notes-writer-gitlab-org create MR https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123`), use that MR directly. **Validate that the MR has a `release post item::` label that matches the work item's `release post item::` label** (not just that any `release post item::` label exists). If the labels don't match, warn the PM: *"The MR you linked has `release post item::secondary` but the work item has `release post item::primary`. Please verify this is the correct MR."* Do not proceed. 2. **Search for candidate MRs** — Look for open MRs in `gitlab-org/gitlab` matching a `release post item::` scoped label (`::primary`, `::secondary`, or `::top`) and the current milestone. The `platform:` labels from the work item can also be used to narrow results. This step is only to narrow the initial search. 3. **Verify via work item link** — For each candidate MR, check the MR diff for a reference to the work item URL (the issue/epic link). If the diff does not contain the link, fall back to checking the MR description. This confirms it's the correct MR for this work item, not a different release note item that happens to share labels. ### Sync phase (`@ai-release-notes-writer-gitlab-org sync`) The `sync` command treats the MR as the source of truth and updates the work item description accordingly. It uses the same [MR detection](#mr-detection) logic to find the associated MR. The PM can also provide a MR link directly (e.g., `@ai-release-notes-writer-gitlab-org sync https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123`). When triggered on a MR (via comment or in chat while viewing an MR), the PM can provide a work item link, otherwise the agent will use the MR diff content (or MR description as fallback) to determine the associated work item. - **Existing MR/work item found:** the agent compares the release notes content in the MR's committed `.md` file with the `## Release notes` section in the work item description. - **If they differ:** the agent updates the work item's `## Release notes` section with the content from the MR, and replies: *"Synced the release notes from !123 to this work item. The MR remains the source of truth."* - **If they are the same:** the agent replies: *"The release notes in this work item and !123 are already in sync. No changes made."* - **No existing MR found:** the agent replies: *"No existing MR was found for this work item. Use `create MR` to create one first."* ### MR assignment The MR is always assigned to whoever triggered the agent — the person who did the at-mention (via Flow) or the current user (via Duo Chat). ### Tier label inference If at least one tier label is present, higher tiers are inferred automatically: - `GitLab Free` present → available in Free, Premium, and Ultimate - `GitLab Premium` present → available in Premium and Ultimate - `GitLab Ultimate` present → available in Ultimate only The agent should apply this inference when validating labels and generating the MR content. ### Error handling If the agent encounters an error during any phase (e.g., API failures when creating a commit, MR creation permission errors, branch conflicts, or unexpected tool errors), it must **always reply to the mentioner with a comment** explaining: - What action it was attempting (e.g., "I was trying to create the MR in `gitlab-org/gitlab`") - The error encountered (include relevant error details such as error messages or HTTP status codes) - A suggested next step (e.g., "Please retry by commenting `create MR` again, or check that the service account has write access to the target project") The agent should never fail silently. If it cannot complete the requested action, the PM must be informed. ### Comments posted by the Flow All comments posted by the agent via the Flow should include a line at the bottom identifying the source, for example: > _Automated by the [release-notes-writer](https://gitlab.com/components/agents-and-flows/release-notes-writer) agent._ When the agent is invoked via **Duo Chat**, it should include a link to the [agent project](https://gitlab.com/components/agents-and-flows/release-notes-writer) only when the PM asks for it (e.g., "where can I suggest improvements?" or "where is the agent project?"). ## PM workflow ```mermaid flowchart TD A[PM adds ~release post item::primary\nor ::secondary / ::top] --> B["PM comments\n@ai-release-notes-writer-gitlab-org create MR"] B --> C[Flow triggers agent] C --> L{## Release notes\nsection present?} L -->|No| D[Agent drafts and updates\n## Release notes section] D --> N L -->|Yes| D2{Significant differences\nbetween agent draft\nand existing section?} D2 -->|Yes| D3[Agent updates description\nwith improved version] D2 -->|No| D4[Agent keeps existing section as-is] D3 --> N D4 --> N N{Blocking issues?\ncategorization label\ntier label\nplatform label} N -->|Yes| O["Agent replies with ONE comment:\n- What it did (drafted/updated section)\n- Missing labels\n- Suggested quick actions\n- Prose revision if applicable"] O --> P["PM addresses gaps\nre-mentions create MR"] P --> C N -->|No| MR{Existing MR\ndetected?} MR -->|Yes| TS{Work item newer\nthan latest MR commit?} TS -->|Yes| UPD[Agent creates new commit\non existing MR branch\nwith regenerated content] TS -->|No| WARN["Agent warns PM:\nMR commit is newer than work item\nAsk PM to confirm with --force"] MR -->|No| Q[Agent searches for docs link if missing\nCreates MR in gitlab-org/gitlab\nusing Release Notes Item template\nassigned to mentioner\nLinks work item in MR description\nAdds handoff note to work item description] UPD --> R2["Agent replies with ONE comment:\nMR link + updated confirmation\n+ source of truth handoff"] Q --> R["Agent replies with ONE comment:\nMR link + notes + warnings\n+ source of truth handoff"] ``` ### Draft-only workflow ```mermaid flowchart TD A["PM comments\n@ai-release-notes-writer-gitlab-org draft"] --> B[Flow triggers agent] B --> L{## Release notes\nsection present?} L -->|No| D[Agent drafts and updates\n## Release notes section\nReplies confirming + any discrepancies] L -->|Yes| D2{Significant differences?} D2 -->|Yes| D3[Agent updates description\nReplies explaining changes] D2 -->|No| D4[Agent does NOT update\nReplies confirming looks good\n+ minor suggestions if any] ``` ### Sync workflow ```mermaid flowchart TD A["PM comments\n@ai-release-notes-writer-gitlab-org sync\n(optionally with MR link)"] --> B[Flow triggers agent] B --> C{MR detection} C -->|MR found| D[Compare MR content\nvs work item description] D -->|Different| E[Update work item description\nfrom MR content\nMR is source of truth] D -->|Same| G["Reply: Already in sync\nNo changes made"] E --> H["Reply: Synced from MR\nMR remains source of truth"] C -->|No MR found| J["Reply: No MR found\nUse create MR first"] ``` ### Triggering from a MR ```mermaid flowchart TD A["PM comments on MR:\n@ai-release-notes-writer-gitlab-org create MR"] --> B[Agent looks up related work item] B --> C{Work item found?} C -->|PM provided link| D[Use provided work item] C -->|Found in MR diff| D C -->|Found in MR description| D C -->|Not found| E["Reply: Please provide\na work item link"] D --> F[Continue with normal\ncreate MR flow\nusing found work item] ``` ## Suggested label flow The `release post item::` scoped labels (`::primary`, `::secondary`, `::top`) are used for **categorization** and must remain on the work item throughout the process. These are the only labels involved — there are no workflow state labels for this process. ## Future improvement: label-based triggering The current `mention` trigger requires the PM to type a comment. When GitLab adds support for label-based flow triggers, this process could be migrated to use labels instead (e.g. `release notes item creation::draft` and `::ready`), making the workflow more seamless. No feature request exists for this yet — one should be filed with the Duo Agent Platform team. ## Implementation Both changes are made in the existing [`components/agents-and-flows/release-notes-writer`](https://gitlab.com/components/agents-and-flows/release-notes-writer) project, following the [Agents and Flows README](https://gitlab.com/groups/components/agents-and-flows) process. ### Part 1: Extend `agents/agent.yml` Extend the existing system prompt — **do not replace it** — to add: - **Help command** (triggered by `help` or unrecognized keyword): - Reply with a summary of available commands (`draft`/`redraft`, `create MR`/`update MR`/`ready`, `sync`, `help`) and their syntax - Include a link to any relevant documentation or the agent project README for more details - **Draft mode instructions** (triggered by `draft` or `redraft`): - If no `## Release notes` section exists: draft one and update the work item description; reply to the mentioner confirming the section was added, including any discrepancies or missing info in the same reply - If a `## Release notes` section already exists: compare the agent's suggested draft against the existing section. If there are significant differences, update the description with the improved version and reply explaining what changed. If the existing section is already in good shape, do not update the description; reply confirming it looks good with any minor suggestions. - **MR creation/update instructions** (triggered by `create MR`, `update MR`, or `ready`): - Combines drafting and MR creation into a single pass with **one consolidated reply** at the end - If no `## Release notes` section exists: run the draft process first, then continue (do not stop or post a separate comment) - If blocking issues are found: reply to the mentioner with **one comment** listing what was accomplished, the missing labels, **suggested quick action(s)** the PM can copy-paste to apply them (e.g., `/label ~"release post item::primary"`), and any prose revision if applicable - If all required info is present: run [MR detection](#mr-detection); if existing MR found, check timestamps (work item updated vs. latest MR commit) and update or warn accordingly; if no existing MR, search for a docs link if one is not already in the `## Release notes` section (using `gitlab_documentation_search`), generate the Hugo leaf bundle `.md` file, create the MR in `gitlab-org/gitlab` using the [Release Notes Item template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/Release%20Notes%20Item.md) assigned to the mentioner with the work item linked in the description; add handoff note to work item description; reply to the mentioner with **one comment** containing the MR link, any relevant notes (including non-blocking warnings), and the source-of-truth handoff message - **Sync instructions** (triggered by `sync`): - Run [MR detection](#mr-detection); if existing MR found, treat MR as source of truth and update work item description if they differ; if no MR found, reply asking the PM to use `create MR` first - **Case insensitivity**: all command keywords must be matched case-insensitively - **Work item context**: the agent operates on the work item where the comment was posted by default; if the PM provides a work item link in their comment, use that instead; if invoked via Duo Chat without context and no link provided, ask the PM for a link - **MR-triggered context**: when triggered from a MR comment, look up the related work item via PM-provided link, MR diff content, or MR description (in that order) - **MR detection logic**: three-step matching (PM-provided link with matching `release post item::` label validation → search by `release post item::` + milestone + optionally `platform:` labels to narrow results → verify via work item URL in MR diff, falling back to MR description) - **Timestamp comparison for MR updates**: when an existing MR is detected, compare the work item's last updated timestamp against the latest MR commit timestamp; only update if work item is newer; if MR is newer, warn PM and require `--force` to proceed - **Source of truth handoff**: all replies after MR creation/update must include the handoff message; the work item description must be updated with a visible handoff note linking to the MR - **MR assignment**: always assigned to whoever triggered the agent — the mentioner (via Flow) or the current user (via Duo Chat) - **Tier inference**: if at least one tier label is present, infer higher tiers accordingly - **Error handling**: if any tool call or API operation fails, the agent must reply to the mentioner with a comment explaining what it was attempting, the error encountered (with relevant details), and a suggested next step. The agent must never fail silently. - **Comment footer**: all comments posted via the Flow must include a line at the bottom identifying the source (see [Comments posted by the Flow](#comments-posted-by-the-flow)). When invoked via Duo Chat, only include the agent project link when the PM asks for it. **Additional tools to add to `agents/agent.yml`:** | Tool | Purpose | |------|---------| | `create_merge_request` | Create the MR in the target project | | `create_commit` | Commit the generated `.md` file to the MR branch | | `create_work_item_note` | Reply to the mentioner on the work item | ### Part 2: Add `flows/flow.yml` Add a Flow to the same project (based on [`flows/flow.yml.template`](https://gitlab.com/components/agents-and-flows/release-notes-writer/-/blob/main/flows/flow.yml.template)) to automatically invoke the agent when the service account is at-mentioned on a work item. **Flow configuration:** - `consumers`: scoped to the `gitlab-org` group (ID: 9970) - `trigger_types`: `mention` - The agent reads the triggering comment to determine mode (case-insensitive): `help`, `draft`/`redraft`, `create MR`/`update MR`/`ready`, or `sync` - `toolset`: same tools as the agent (including `create_merge_request`, `create_commit`, `create_work_item_note`) ### Step 3: Verify 1. Comment `@ai-release-notes-writer-gitlab-org help` — confirm the agent replies with a summary of available commands and their syntax. 2. Comment `@ai-release-notes-writer-gitlab-org` with no keyword or an unrecognized keyword — confirm the agent replies with the help summary. 3. Comment `@ai-release-notes-writer-gitlab-org DRAFT` (uppercase) — confirm case-insensitive matching works. 4. Comment `@ai-release-notes-writer-gitlab-org draft` on a work item **with no `## Release notes` section** — confirm the agent drafts the section, updates the description, and replies to the mentioner (with discrepancy report if applicable). 5. Comment `@ai-release-notes-writer-gitlab-org draft` on a work item **with an existing `## Release notes` section that has significant gaps** — confirm the agent updates the description with the improved version and replies explaining what changed. 6. Comment `@ai-release-notes-writer-gitlab-org redraft` on a work item **with an existing `## Release notes` section that is already in good shape** — confirm the agent does not update the description and replies confirming it looks good, with any minor suggestions. 7. Comment `@ai-release-notes-writer-gitlab-org create MR` on a work item **with no `## Release notes` section and all required labels** — confirm the agent drafts the section, continues to MR creation without stopping, and replies with **one comment** containing the MR link and notes. 8. Comment `@ai-release-notes-writer-gitlab-org update MR` on a work item — confirm it behaves identically to `create MR`. 9. Comment `@ai-release-notes-writer-gitlab-org create MR` on a work item **with no `## Release notes` section and missing required labels** — confirm the agent drafts the section, then replies with **one comment** listing what it did (drafted section), the missing labels, and suggested quick actions. 10. Comment `@ai-release-notes-writer-gitlab-org ready` on a work item **with blocking issues** (missing categorization label, tier label, or platform label) — confirm the agent replies with details, suggested quick actions to apply the missing labels, and includes any prose revision suggestion. 11. Comment `@ai-release-notes-writer-gitlab-org create MR` on a work item **without a docs link** — confirm the agent searches for and includes a docs link when creating the MR. 12. Comment `@ai-release-notes-writer-gitlab-org create MR` on a complete work item **with no existing MR** — confirm the agent creates the MR in `gitlab-org/gitlab` using the Release Notes Item template, assigned to the mentioner, with the work item linked in the description, adds the handoff note to the work item description, and replies with the MR link, notes, and source-of-truth handoff message. 13. Comment `@ai-release-notes-writer-gitlab-org create MR` on a work item **with an existing MR where the work item is newer** — confirm the agent detects the existing MR, creates a new commit with regenerated content, and replies with the MR link and update confirmation. 14. Comment `@ai-release-notes-writer-gitlab-org create MR` on a work item **with an existing MR where the MR commit is newer** — confirm the agent warns the PM about the timestamp mismatch and does not update the MR. 15. Comment `@ai-release-notes-writer-gitlab-org create MR --force` on a work item **with an existing MR where the MR commit is newer** — confirm the agent proceeds with the update despite the timestamp mismatch. 16. Comment `@ai-release-notes-writer-gitlab-org create MR https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123` where the MR has a **matching** `release post item::` label — confirm the agent uses the provided MR link and proceeds. 17. Comment `@ai-release-notes-writer-gitlab-org create MR https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123` where the MR has a **mismatched** `release post item::` label (e.g., MR has `::secondary` but work item has `::primary`) — confirm the agent warns the PM about the mismatch and does not proceed. 18. Comment `@ai-release-notes-writer-gitlab-org sync` on a work item **with an existing MR where the content differs** — confirm the agent updates the work item description from the MR content and replies confirming the sync. 19. Comment `@ai-release-notes-writer-gitlab-org sync` on a work item **with an existing MR where content is already in sync** — confirm the agent replies that no changes were needed. 20. Comment `@ai-release-notes-writer-gitlab-org sync` on a work item **with no existing MR** — confirm the agent replies asking the PM to use `create MR` first. 21. Comment `@ai-release-notes-writer-gitlab-org sync https://gitlab.com/gitlab-org/gitlab/-/merge_requests/123` — confirm the agent uses the provided MR link for sync. 22. Comment `@ai-release-notes-writer-gitlab-org create MR` **on a MR** (not a work item) — confirm the agent looks up the related work item from the MR diff/description and proceeds. 23. Comment `@ai-release-notes-writer-gitlab-org create MR` **on a MR** where no related work item can be found — confirm the agent asks the PM to provide a work item link. 24. Comment `@ai-release-notes-writer-gitlab-org create MR https://gitlab.com/gitlab-org/gitlab/-/issues/456` on a work item, providing a **different work item link** — confirm the agent uses the linked work item instead of the current one. 25. Invoke the agent via **Duo Chat** without providing a work item link — confirm the agent asks the PM to provide a link. 26. Verify that **every comment** posted by the agent (via Flow) includes the footer with the agent attribution line. 27. Invoke the agent via **Duo Chat**, ask "where is the agent project?" — confirm the response includes a link to the agent project. 28. Simulate a tool failure (e.g., permission error on MR creation) — confirm the agent replies to the mentioner with a clear error message explaining what it was attempting, the error details, and a suggested next step.