From 84798c24f8aa0d586ae287383f62382bcc29dd15 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Fri, 24 Apr 2026 18:48:56 +0530 Subject: [PATCH 1/2] feat(docs-tools): add optional Slack MCP integration for requirements and planning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enable the requirements-analyst and docs-planner agents to search Slack for SME decisions, design rationale, and technical context not captured in JIRA tickets or PRs. The integration is optional — agents detect Slack MCP tool availability at runtime and skip Slack research if not configured. Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/README.md | 31 +++++++++++++++++++ plugins/docs-tools/agents/docs-planner.md | 1 + .../docs-tools/agents/requirements-analyst.md | 26 +++++++++++++++- 3 files changed, 57 insertions(+), 1 deletion(-) diff --git a/plugins/docs-tools/README.md b/plugins/docs-tools/README.md index f24e3688..6d4409f1 100644 --- a/plugins/docs-tools/README.md +++ b/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. diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index fffaddc3..d6c71c48 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -50,6 +50,7 @@ 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 + - If Slack MCP tools are available (`mcp__slack__*`), search Slack for additional context on ambiguous requirements — search by ticket key or feature name to find SME decisions, design rationale, or technical details not captured in JIRA. Cross-reference any Slack findings against the codebase before incorporating them. 3. **Assess documentation impact**: - Grade each requirement using the impact assessment criteria below diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index 613d80e0..bcfa986c 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -139,7 +139,31 @@ 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 if Slack MCP is not configured. + +**Search strategy:** + +1. **Search by ticket key**: Use `mcp__slack__search_messages` with the JIRA ticket key (e.g., `PROJECT-123`) to find discussions across all accessible channels. +2. **Search by feature name**: Search for the feature name, component name, or technical terms from the ticket summary. +3. **Follow threads**: When search results reference a thread, use `mcp__slack__get_thread` to read the full conversation for context. + +**What to look for:** + +- SME decisions or rationale not captured in JIRA ("we decided to..." / "the reason is...") +- Technical details shared in engineering channels +- Design discussions that inform documentation scope +- Stakeholder concerns or user pain points mentioned in conversation + +**Record Slack findings:** + +Add relevant Slack context to the "Sources consulted" section: +- `Slack thread in #channel-name (YYYY-MM-DD): [Summary of relevant discussion]` + +**Important:** Slack conversations are informal. Cross-reference any technical claims against the codebase or JIRA before treating them as documentation-ready facts. + +### 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. From d9e46eeb75de6bd8b1ec6f8f46227865d35b4147 Mon Sep 17 00:00:00 2001 From: Gaurav Trivedi Date: Fri, 24 Apr 2026 18:54:12 +0530 Subject: [PATCH 2/2] chore(docs-tools): bump version to 0.0.48 Co-Authored-By: Claude Opus 4.6 --- plugins/docs-tools/.claude-plugin/plugin.json | 2 +- plugins/docs-tools/agents/docs-planner.md | 5 +- .../docs-tools/agents/requirements-analyst.md | 54 ++++++++++++++----- 3 files changed, 47 insertions(+), 14 deletions(-) diff --git a/plugins/docs-tools/.claude-plugin/plugin.json b/plugins/docs-tools/.claude-plugin/plugin.json index 0c762e59..416ed14e 100644 --- a/plugins/docs-tools/.claude-plugin/plugin.json +++ b/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", diff --git a/plugins/docs-tools/agents/docs-planner.md b/plugins/docs-tools/agents/docs-planner.md index d6c71c48..12151a17 100644 --- a/plugins/docs-tools/agents/docs-planner.md +++ b/plugins/docs-tools/agents/docs-planner.md @@ -50,7 +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 - - If Slack MCP tools are available (`mcp__slack__*`), search Slack for additional context on ambiguous requirements — search by ticket key or feature name to find SME decisions, design rationale, or technical details not captured in JIRA. Cross-reference any Slack findings against the codebase before incorporating them. + - **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 diff --git a/plugins/docs-tools/agents/requirements-analyst.md b/plugins/docs-tools/agents/requirements-analyst.md index bcfa986c..68556808 100644 --- a/plugins/docs-tools/agents/requirements-analyst.md +++ b/plugins/docs-tools/agents/requirements-analyst.md @@ -141,27 +141,57 @@ The `--graph` flag discovers custom field IDs, fetches the parent, children, sib ### 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 if Slack MCP is not configured. +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:** -1. **Search by ticket key**: Use `mcp__slack__search_messages` with the JIRA ticket key (e.g., `PROJECT-123`) to find discussions across all accessible channels. -2. **Search by feature name**: Search for the feature name, component name, or technical terms from the ticket summary. -3. **Follow threads**: When search results reference a thread, use `mcp__slack__get_thread` to read the full conversation for context. +Run these searches in order. Stop early if the first search already provides sufficient context. -**What to look for:** +1. **Search by ticket key** — searches all channels the user has access to: + ``` + mcp__slack__search_messages query: "PROJECT-123" + ``` -- SME decisions or rationale not captured in JIRA ("we decided to..." / "the reason is...") -- Technical details shared in engineering channels -- Design discussions that inform documentation scope -- Stakeholder concerns or user pain points mentioned in conversation +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: -- `Slack thread in #channel-name (YYYY-MM-DD): [Summary of relevant discussion]` +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. +``` -**Important:** Slack conversations are informal. Cross-reference any technical claims against the codebase or JIRA before treating them as documentation-ready facts. +**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