## Problem Once the Slack messaging integration is available to users, there will be no user-facing documentation explaining how the feature works, how to set it up, or what to expect. The [ADR 008](https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/19020) covers the architecture but is not a user doc. ## Proposal Create user-facing documentation. The exact scope will depend on what ships and how the feature evolves, but the following areas should be covered: ### User guide - How to trigger Duo from Slack (`@Duo <task>` in any channel where the bot is installed) - Thread context: Duo reads the full conversation thread as context for the task - Response lifecycle: :eyes: reaction → agent works → threaded reply with result → :white_check_mark: reaction - Error states and what they mean ### Setup / prerequisites - GitLab Slack integration must be installed with bot capabilities - User must have a linked Slack :left_right_arrow: GitLab account - User must have `duo_default_namespace` configured (or be prompted to set it) - Duo seat must be available in the namespace ### Slack app permissions The Duo Slack integration requires the following additional OAuth scopes beyond the base GitLab Slack app: | Scope | Purpose | |-------|---------| | `app_mentions:read` | Allows the bot to receive events when a user `@mentions` it in a channel | | `channels:history` | Reads public channel conversation history to provide thread context to the agent | | `groups:history` | Reads private channel conversation history to provide thread context to the agent | | `reactions:write` | Adds emoji reactions (`:eyes:`, `:white_check_mark:`) to messages to indicate agent lifecycle status | **Note:** These scopes are added to the GitLab Slack app manifest. Existing workspace installations will only receive the new scopes after re-authorizing (reinstalling) the app. New installations will get them automatically. The `channels:history` and `groups:history` scopes mean that conversation content is sent to an LLM — this should be clearly communicated to users and administrators. ### Customization - What the `duo-workspace` project is and when it gets created - How to customize the agent environment (Docker image, `AGENTS.md`, CI/CD variables, runner tags) This is a placeholder issue — the specifics will be refined as the implementation lands and the feature matures toward GA. ### Error message updates We currently have a bunch of error messages in the `app_mention_service.rb` and potentially also in the slack messaging adapter to be built. We should adjust the error messages and add a link to the docs. ## Related - Parent issue: https://gitlab.com/gitlab-org/gitlab/-/work_items/590434 - ADR: https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/19020 - Manifest & dogfooding decisions: https://gitlab.com/gitlab-org/gitlab/-/work_items/598661