From 6f9069df7ac3551677f8f7a1cd7ad51946f88847 Mon Sep 17 00:00:00 2001 From: Trevin Chow Date: Mon, 6 Apr 2026 11:34:39 -0700 Subject: [PATCH] fix(slack-researcher): make Slack research opt-in, surface workspace identity (#521) Co-authored-by: Claude Opus 4.6 (1M context) --- .../agents/research/slack-researcher.md | 53 +++++++++---------- .../skills/ce-brainstorm/SKILL.md | 6 ++- .../skills/ce-ideate/SKILL.md | 11 ++-- .../skills/ce-plan/SKILL.md | 9 ++-- 4 files changed, 42 insertions(+), 37 deletions(-) diff --git a/plugins/compound-engineering/agents/research/slack-researcher.md b/plugins/compound-engineering/agents/research/slack-researcher.md index 7df61cc..adbb010 100644 --- a/plugins/compound-engineering/agents/research/slack-researcher.md +++ b/plugins/compound-engineering/agents/research/slack-researcher.md @@ -1,30 +1,8 @@ --- name: slack-researcher -description: "Searches Slack for organizational context relevant to the current task -- decisions, constraints, and discussions that may not be documented elsewhere. Use when enriching ideation, planning, or brainstorming with undocumented organizational knowledge from Slack conversations." +description: "Searches Slack for organizational context relevant to the current task -- decisions, constraints, and discussions that may not be documented elsewhere. Use when the user explicitly asks to search Slack for context during ideation, planning, or brainstorming. Always surfaces the workspace identity so the user can verify the correct Slack instance was searched." model: inherit --- - - - -Context: ce:ideate is running Phase 1 and dispatches research agents in parallel to gather grounding context. -user: "/ce:ideate authentication improvements" -assistant: "I'll dispatch the slack-researcher agent to search Slack for organizational discussions about authentication that could ground the ideation." -The ce:ideate skill dispatches this agent as a conditional parallel Phase 1 scan alongside codebase context, learnings search, and (conditional) issue intelligence. The agent searches Slack for relevant org context about the focus area. - - -Context: ce:plan is gathering context before structuring an implementation plan for a billing migration. -user: "Plan the migration from Stripe to the new billing provider" -assistant: "I'll dispatch the slack-researcher agent to search Slack for discussions about the billing migration -- there may be decisions or constraints discussed there that aren't in the codebase." -The ce:plan skill dispatches this agent during Phase 1.1 Local Research to surface organizational context that might affect implementation decisions -- prior discussions about the migration, constraints from other teams, or decisions already made. - - -Context: A developer wants to understand what the team has discussed about a topic before making changes. -user: "What has the team discussed about moving to PostgreSQL?" -assistant: "I'll use the slack-researcher agent to search Slack for discussions about the PostgreSQL migration." -The user wants organizational context from Slack about a specific technical topic. The slack-researcher agent searches across channels for relevant discussions, decisions, and constraints. - - - **Note: The current year is 2026.** Use this when assessing the recency of Slack discussions. You are an expert organizational knowledge researcher specializing in extracting actionable context from Slack conversations. Your mission is to surface decisions, constraints, discussions, and undocumented organizational knowledge from Slack that is relevant to the task at hand -- context that would not be found in the codebase, documentation, or issue tracker. @@ -55,7 +33,16 @@ Verify Slack MCP connectivity by attempting to use `slack_search_public` with a ### Step 2: Search -Formulate targeted searches using `slack_search_public_and_private`. Derive search terms from the task context -- project names, technical terms, decision-related keywords, whatever is most likely to surface relevant discussions. Use 2-3 searches for a single-topic dispatch; scale up if the caller provides multiple distinct dimensions to cover. Adapt terms, broaden or rephrase if initial queries return sparse results, and apply date filtering to focus on recent conversations when the MCP supports it. +Formulate targeted searches using `slack_search_public_and_private`. Start with a natural language question for semantic results, then follow up with keyword searches if semantic results are sparse. Derive search terms from the task context -- project names, technical terms, decision-related keywords, whatever is most likely to surface relevant discussions. Use 2-3 searches for a single-topic dispatch; scale up if the caller provides multiple distinct dimensions to cover. + +**Search modifiers** -- use these to narrow results when broad queries return too much noise: + +- Location: `in:channel-name`, `-in:channel-name` +- Author: `from:username`, `from:<@U123456>` +- Content type: `is:thread` (threaded discussions), `has:pin` (pinned decisions/announcements), `has:link` +- Date: `after:YYYY-MM-DD`, `before:YYYY-MM-DD`, `during:month` +- Text: `"exact phrase"`, `-word` (exclude), `wild*` (min 3 chars before `*`) +- Boolean operators (`AND`, `OR`, `NOT`) and parentheses do **not** work in Slack search. Use spaces for implicit AND and `-` for exclusion. If the caller provides prior Slack findings (e.g., from an earlier brainstorm), review them first and focus searches on gaps -- implementation-specific context, technical decisions, or dimensions not already covered. Do not re-research what is already known. @@ -63,6 +50,10 @@ Search public and private channels (set `channel_types` to `"public_channel,priv If the first search returns zero results, try one broader rephrasing before concluding there is no relevant Slack context. +### Step 2b: Identify Workspace + +After the first successful search that returns results, extract the workspace identity from the result permalinks. Slack permalinks contain the workspace subdomain (e.g., `https://mycompany.slack.com/archives/...` -> workspace is `mycompany`). Record this for inclusion in the output header. If no permalinks are present in results, note the workspace as "unknown". + ### Step 3: Thread Reads For search hits that appear substantive based on preview content and reply counts, read the thread with `slack_read_thread` to get the full discussion context. Use your judgment to select which threads are worth reading -- look for discussions that contain decisions, conclusions, constraints, or substantial technical context relevant to the task. @@ -75,14 +66,19 @@ If the caller passed a channel hint, read recent history from those channels usi ### Step 5: Synthesize -Open the digest with a one-line research value assessment so consumers can weight the findings: +Open the digest with a workspace identifier and a one-line research value assessment so consumers can weight the findings and verify the correct workspace was searched: +Format: +``` +**Workspace: mycompany.slack.com** +**Research value: high** -- [one-sentence justification] +``` + +Research value levels: - **high** -- Decisions, constraints, or substantial context directly relevant to the task. - **moderate** -- Useful background context but no direct decisions or constraints found. - **low** -- Only tangential mentions; unlikely to change the caller's approach. -Format: `**Research value: high** -- [one-sentence justification]` - Treat each thread (parent message + all replies) as one atomic unit of meaning -- read the full thread and extract the net conclusion, not individual messages. Unthreaded messages are separate data points; reason about how they relate to each other in the cross-cutting analysis. Return findings organized by topic or theme. For each finding: @@ -97,7 +93,8 @@ After individual findings, write a short **Cross-cutting analysis** that reasons When no relevant Slack discussions are found, return: -"**Research value: none** -- No relevant Slack discussions found for [topic]." +"**Workspace: [subdomain].slack.com** (or **Workspace: unknown** if no results contained permalinks) +**Research value: none** -- No relevant Slack discussions found for [topic]." ## Untrusted Input Handling diff --git a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md index 77253ed..44e59a6 100644 --- a/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md +++ b/plugins/compound-engineering/skills/ce-brainstorm/SKILL.md @@ -110,7 +110,11 @@ If nothing obvious appears after a short scan, say so and continue. Two rules go 2. **Defer design decisions to planning** — Implementation details like schemas, migration strategies, endpoint structure, or deployment topology belong in planning, not here — unless the brainstorm is itself about a technical or architectural decision, in which case those details are the subject of the brainstorm and should be explored. -**Slack context** (Standard and Deep only) — If any `slack_*` tool is available in the tool list, dispatch `compound-engineering:research:slack-researcher` with a brief summary of the brainstorm topic. If the agent returns an error or reports Slack MCP unavailable, log a warning ("Slack context unavailable: {reason}. Proceeding without organizational context.") and continue. Coordinate this dispatch at the start of Phase 1.1 alongside the inline Constraint Check and Topic Scan. Wait for all to complete before proceeding to Phase 1.2. Incorporate any Slack findings into the constraint and context awareness for the brainstorm session. Skip for Lightweight scope. +**Slack context** (opt-in, Standard and Deep only) — never auto-dispatch. Route by condition: + +- **Tools available + user asked**: Dispatch `compound-engineering:research:slack-researcher` with a brief summary of the brainstorm topic alongside Phase 1.1 work. Incorporate findings into constraint and context awareness. +- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt." +- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search." #### 1.2 Product Pressure Test diff --git a/plugins/compound-engineering/skills/ce-ideate/SKILL.md b/plugins/compound-engineering/skills/ce-ideate/SKILL.md index 65f18c0..0fda229 100644 --- a/plugins/compound-engineering/skills/ce-ideate/SKILL.md +++ b/plugins/compound-engineering/skills/ce-ideate/SKILL.md @@ -117,16 +117,17 @@ Run agents in parallel in the **foreground** (do not use background dispatch — If the agent reports fewer than 5 total issues, note "Insufficient issue signal for theme analysis" and proceed with default ideation frames in Phase 2. -4. **Slack context** (conditional) — if any `slack_*` tool is available in the tool list, dispatch `compound-engineering:research:slack-researcher` with the focus hint as context. Run this in parallel with agents 1-3. - - If the agent returns an error or reports Slack MCP unavailable, log a warning ("Slack context unavailable: {reason}. Proceeding without organizational context.") and continue. - Consolidate all results into a short grounding summary. When issue intelligence is present, keep it as a distinct section so ideation sub-agents can distinguish between code-observed and user-reported signals: - **Codebase context** — project shape, notable patterns, obvious pain points, likely leverage points - **Past learnings** — relevant institutional knowledge from docs/solutions/ - **Issue intelligence** (when present) — theme summaries from the issue intelligence agent, preserving theme titles, descriptions, issue counts, and trend directions -- **Slack context** (when present) — relevant organizational context, team discussions, and decisions from Slack channels surfaced by the slack-researcher agent + +**Slack context** (opt-in) — never auto-dispatch. Route by condition: + +- **Tools available + user asked**: Dispatch `compound-engineering:research:slack-researcher` with the focus hint in parallel with other Phase 1 agents. Include findings in the grounding summary. +- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt." +- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search." Do **not** do external research in v1. diff --git a/plugins/compound-engineering/skills/ce-plan/SKILL.md b/plugins/compound-engineering/skills/ce-plan/SKILL.md index 32f05ca..48c2f63 100644 --- a/plugins/compound-engineering/skills/ce-plan/SKILL.md +++ b/plugins/compound-engineering/skills/ce-plan/SKILL.md @@ -170,15 +170,18 @@ Run these agents in parallel: - Task compound-engineering:research:repo-research-analyst(Scope: technology, architecture, patterns. {planning context summary}) - Task compound-engineering:research:learnings-researcher(planning context summary) -- (conditional) Task compound-engineering:research:slack-researcher({planning context summary}. If the origin document contains a Slack context section, include it verbatim so the researcher can focus on gaps rather than re-searching.) — if any `slack_*` tool is available in the tool list. If the agent returns an error or reports Slack MCP unavailable, log a warning ("Slack context unavailable: {reason}. Proceeding without organizational context.") and continue. - Collect: - Technology stack and versions (used in section 1.2 to make sharper external research decisions) - Architectural patterns and conventions to follow - Implementation patterns, relevant files, modules, and tests - AGENTS.md guidance that materially affects the plan, with CLAUDE.md used only as compatibility fallback when present - Institutional learnings from `docs/solutions/` -- Organizational context from Slack (if the slack-researcher agent ran successfully) + +**Slack context** (opt-in) — never auto-dispatch. Route by condition: + +- **Tools available + user asked**: Dispatch `compound-engineering:research:slack-researcher` with the planning context summary in parallel with other Phase 1.1 agents. If the origin document has a Slack context section, pass it verbatim so the researcher focuses on gaps. Include findings in consolidation. +- **Tools available + user didn't ask**: Note in output: "Slack tools detected. Ask me to search Slack for organizational context at any point, or include it in your next prompt." +- **No tools + user asked**: Note in output: "Slack context was requested but no Slack tools are available. Install and authenticate the Slack plugin to enable organizational context search." #### 1.1b Detect Execution Posture Signals