feat(docs-tools): add optional Slack MCP integration

plugins/docs-tools/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "docs-tools",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "description": "Documentation review, writing, and workflow tools for Red Hat AsciiDoc and Markdown documentation.",
   "author": {
     "name": "Red Hat Documentation Team",

plugins/docs-tools/README.md

@@ -36,6 +36,37 @@
 
     Restart your terminal and Claude Code for changes to take effect.
 
+### Optional: Slack MCP server
+
+The Slack MCP server allows the requirements analyst and docs planner agents to search Slack conversations for additional context — SME decisions, design rationale, and technical details that may not be captured in JIRA tickets or PRs. This integration is optional; the workflow operates normally without it.
+
+**Benefits:**
+
+- Search Slack channels and DMs for discussions about a JIRA ticket or feature
+- Read full thread conversations to recover decision rationale
+- Access channel history for context during documentation research
+- Identify SMEs who have been discussing a feature
+
+**Prerequisites:** Python 3, Podman or Docker
+
+**Setup:**
+
+```bash
+python3 <(curl -fsSL https://raw.githubusercontent.com/redhat-community-ai-tools/slack-mcp/main/scripts/setup-slack-mcp.py)
+```
+
+The setup script handles everything: Python venv, Playwright, token extraction, wrapper script, and Claude Code registration. You only need to log into Slack when the browser opens and provide a channel ID for server logs (use a self-DM or Slackbot DM).
+
+After setup, restart Claude Code to activate the Slack MCP server.
+
+To refresh tokens when they expire:
+
+```bash
+python3 ~/.local/share/slack-mcp/setup-slack-mcp.py --refresh-tokens
+```
+
+GitHub repo: [redhat-community-ai-tools/slack-mcp](https://github.com/redhat-community-ai-tools/slack-mcp)
+
 ## Customizing the docs workflow
 
 The docs orchestrator (`/docs-orchestrator`) runs a YAML-defined step list. You can customize it per-repo without modifying the plugin.

plugins/docs-tools/agents/docs-planner.md

@@ -50,6 +50,10 @@ If access to JIRA or Git is needed for supplemental research and fails, **STOP I
    - Summarize each requirement into a dense factual summary (max 150 words per source)
    - Focus on: user-facing changes, API/config changes, new or removed capabilities
    - Flag ambiguous or incomplete requirements for follow-up
+   - **Slack supplemental lookup** (optional — skip if `mcp__slack__*` tools are not available):
+     - For each ambiguous or incomplete requirement, search Slack by ticket key or feature name: `mcp__slack__search_messages query: "PROJECT-123"`
+     - Follow threads with `mcp__slack__get_thread` to recover decision rationale
+     - Verify any Slack findings against the codebase or JIRA before incorporating — Slack is informal and may be outdated
 
 3. **Assess documentation impact**:
    - Grade each requirement using the impact assessment criteria below

plugins/docs-tools/agents/requirements-analyst.md

@@ -139,7 +139,61 @@ The `--graph` flag discovers custom field IDs, fetches the parent, children, sib
 - Find configuration options and parameters
 - Record file paths with line numbers (e.g., `src/feature.ts:45-67`)
 
-### 1.5. Web search expansion
+### 1.5. Slack research (optional)
+
+If Slack MCP tools are available (`mcp__slack__*`), search Slack for additional context that may not be captured in JIRA tickets or PRs. Skip this section entirely if Slack MCP is not configured — it is not an error.
+
+**Search strategy:**
+
+Run these searches in order. Stop early if the first search already provides sufficient context.
+
+1. **Search by ticket key** — searches all channels the user has access to:
+   ```
+   mcp__slack__search_messages query: "PROJECT-123"
+   ```
+
+2. **Search by feature name** — use the feature name, component, or key technical terms from the ticket:
+   ```
+   mcp__slack__search_messages query: "PKCE OAuth flow"
+   ```
+
+3. **Follow threads** — when a search result references a conversation worth reading in full, fetch the complete thread using the channel ID and timestamp from the result:
+   ```
+   mcp__slack__get_thread channel_id: "C0A2WFPBR29" thread_ts: "1776943948.748319"
+   ```
+
+4. **Identify channels by name** (optional) — if you know a likely channel name:
+   ```
+   mcp__slack__get_channel_id_by_name channel_name: "devspaces-docs"
+   ```
+
+**What to extract:**
+
+| Signal | Example phrases | Action |
+|--------|----------------|--------|
+| Decision rationale | "we decided to...", "the reason is..." | Record as context for requirements |
+| Technical details | API names, config flags, architecture notes | Cross-reference against codebase |
+| Scope discussions | "out of scope", "deferred to next release" | Flag as scope boundary |
+| SME identification | People actively discussing the feature | Add to "Who can provide information" |
+| User pain points | "customers are hitting...", "support tickets about..." | Elevate requirement priority |
+
+**Record Slack findings:**
+
+Add relevant Slack context to the "Sources consulted" section using these formats:
+
+- Channel thread: `Slack thread in #channel-name (YYYY-MM-DD): [Summary of relevant discussion]`
+- Direct message: `Slack DM with @username (YYYY-MM-DD): [Summary of relevant discussion]`
+
+**Example:**
+```
+### Slack discussions
+- Slack thread in #team-devspaces (2026-04-20): SME confirmed backup/restore feature targets GA in 3.27. Decision to use CRDs instead of ConfigMap for state storage.
+- Slack DM with @ibuziuk (2026-02-23): PM confirmed stakeholder list for JTBD meeting — UX, Marketing, TAM, and Support contacts identified.
+```
+
+**Reliability guardrail:** Slack conversations are informal and may contain outdated or speculative information. Before incorporating any technical claim into requirements, verify it against at least one authoritative source (codebase, JIRA ticket, or PR). If a Slack finding contradicts JIRA, trust JIRA.
+
+### 1.6. Web search expansion
 
 After gathering initial source materials, expand your research using web search to find additional context, upstream documentation, and industry best practices.