Add Deep Research workflow scaffold

.github/workflows/gh-aw-deep-research.md

@@ -0,0 +1,128 @@
+---
+inlined-imports: true
+name: "Deep Research"
+description: "Deep research assistant for issue comments with web fetch"
+imports:
+  - gh-aw-fragments/elastic-tools.md
+  - gh-aw-fragments/runtime-setup.md
+  - gh-aw-fragments/formatting.md
+  - gh-aw-fragments/rigor.md
+  - gh-aw-fragments/mcp-pagination.md
+  - gh-aw-fragments/messages-footer.md
+  - gh-aw-fragments/safe-output-add-comment.md
+engine:
+  id: gemini
+  model: ${{ inputs.model }}
+  concurrency:
+    group: "gh-aw-gemini-deep-research-${{ github.event.issue.number }}"
+on:
+  workflow_call:
+    inputs:
+      model:
+        description: "AI model to use"
+        type: string
+        required: false
+        default: "gemini-3-pro-preview"
+      additional-instructions:
+        description: "Repo-specific instructions appended to the agent prompt"
+        type: string
+        required: false
+        default: ""
+      setup-commands:
+        description: "Shell commands to run before the agent starts (dependency install, build, etc.)"
+        type: string
+        required: false
+        default: ""
+      allowed-bot-users:
+        description: "Allowlisted bot actor usernames (comma-separated)"
+        type: string
+        required: false
+        default: "github-actions[bot]"
+      messages-footer:
+        description: "Footer appended to all agent comments and reviews"
+        type: string
+        required: false
+        default: ""
+    secrets:
+      GEMINI_API_KEY:
+        required: true
+  reaction: "eyes"
+  roles: [admin, maintainer, write]
+  bots:
+    - "${{ inputs.allowed-bot-users }}"
+concurrency:
+  group: deep-research-${{ github.event.issue.number }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  issues: read
+  pull-requests: read
+tools:
+  github:
+    toolsets: [repos, issues, pull_requests, search]
+  bash: false
+  web-fetch:
+network:
+  firewall: false
+strict: false
+timeout-minutes: 60
+steps:
+  - name: Repo-specific setup
+    if: ${{ inputs.setup-commands != '' }}
+    env:
+      SETUP_COMMANDS: ${{ inputs.setup-commands }}
+    run: eval "$SETUP_COMMANDS"
+---
+
+# Deep Research Assistant
+
+Assist with deep research on ${{ github.repository }} from issue comments, then provide an evidence-backed answer.
+
+## Context
+
+- **Repository**: ${{ github.repository }}
+- **Issue**: #${{ github.event.issue.number }} — ${{ github.event.issue.title }}
+- **Request**: "${{ needs.activation.outputs.text }}"
+
+## Constraints
+
+- **CAN**: Read files, search code, use web fetch, comment on issues
+- **CANNOT**: Execute commands, modify files, run tests, or push to the repository
+
+## Instructions
+
+Understand the request, investigate repository and external context, and respond with a concise, actionable result.
+
+### Step 1: Gather Context and Plan
+
+1. Call `generate_agents_md` to get repository conventions.
+2. Read the full issue thread and any referenced issues. Identify the specific question or goal — this is your research anchor for all subsequent steps.
+3. Before searching, decompose the question into sub-questions. For complex or multi-faceted requests, list 2–5 specific sub-questions that, if answered, would fully address the original request. This prevents unfocused searching and ensures complete coverage.
+4. Use `search_code` and local file reads only when codebase knowledge is needed to answer the question or prepare an implementation.
+
+### Step 2: Research Iteratively
+
+1. Use web fetch as your primary external research method. For each sub-question from Step 1, fetch authoritative sources directly.
+2. After each round of searches, assess what you've learned and what gaps remain. If key sub-questions are still unanswered, search again with refined queries — do not settle for incomplete evidence on important points.
+3. For any key factual claim, seek at least two independent sources. If only one source exists, note this. If sources conflict, investigate further before drawing conclusions — do not present a claim as settled when the evidence is mixed.
+4. Favor primary sources (official documentation, release notes, RFCs, peer-reviewed papers, author blog posts) over secondary summaries or aggregator content. If a claim relies solely on a secondary source, note this.
+5. Before moving to synthesis, re-read your findings against the original research anchor from Step 1. Drop any findings that don't help answer the original question — tangential information dilutes the response.
+
+### Step 3: Verify Before Posting
+
+Before writing the response, apply Chain-of-Verification to your draft findings:
+
+1. For each key claim, generate a specific verification question (e.g., "Is it true that X supports Y as of version Z?"). Answer each verification question using the evidence you gathered — if the evidence doesn't clearly support the claim, either search for confirmation or drop the claim.
+2. If you hedged with "might," "could," or "possibly," the claim is not ready — either confirm it or drop it.
+3. If the research scope was too large to fully investigate, say so explicitly rather than presenting partial findings as complete.
+
+### Step 4: Post Response
+
+Call `add_comment` with a concise response:
+
+1. **Key takeaway** — lead with the direct answer to the original question
+2. **Evidence** — cite specific URLs, docs, or file paths for each claim
+3. **Actions taken** (including validation results)
+4. **Open questions** — if anything could not be confirmed or conflicting evidence was found, list it here rather than omitting silently
+
+${{ inputs.additional-instructions }}

.github/workflows/trigger-deep-research.yml

@@ -0,0 +1,22 @@
+# This file is auto-generated by scripts/dogfood.sh. Do not edit directly.
+# Edit gh-agent-workflows/deep-research/example.yml and run 'make compile' to regenerate.
+name: Trigger Deep Research
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  actions: read
+  contents: read
+  discussions: write
+  issues: write
+  pull-requests: read
+
+jobs:
+  run:
+    if: >-
+      github.event.issue.pull_request == null &&
+      startsWith(github.event.comment.body, '/research')
+    uses: ./.github/workflows/gh-aw-deep-research.lock.yml
+    secrets:
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

gh-agent-workflows/README.md

@@ -35,6 +35,9 @@ Pre-built workflows with domain-specific prompts. These import the same base fra
 - [Text Beautifier](text-beautifier/) — fix text-auditor issues
 - [Code Duplication Fixer](code-duplication-fixer/) — fix code-duplication-detector issues
 
+**Research assistants**:
+- [Deep Research](deep-research/) — issue-comment deep research with web search/fetch and optional PR creation
+
 ## Quick setup script
 
 Run from the repository you want to configure:

gh-agent-workflows/deep-research/README.md

@@ -0,0 +1,38 @@
+# Deep Research
+
+Deep research assistant for issue comments with web fetch.
+
+## How it works
+
+Activated by a comment on an issue (the example trigger uses `/research`). The workflow investigates local code and external sources, then posts an evidence-backed response. It is strictly read-only and does not execute repository commands or implement changes.
+
+## Quick Install
+
+```bash
+mkdir -p .github/workflows && curl -sL \
+  https://raw.githubusercontent.com/elastic/ai-github-actions/v0/gh-agent-workflows/deep-research/example.yml \
+  -o .github/workflows/deep-research.yml
+```
+
+See [example.yml](example.yml) for the full workflow file.
+
+## Trigger
+
+| Event | Types | Condition |
+| --- | --- | --- |
+| `issue_comment` | `created` | Comment on an issue (not a PR); the example trigger filters on `/research` prefix |
+
+## Inputs
+
+| Input | Description | Required | Default |
+| --- | --- | --- | --- |
+| `additional-instructions` | Repo-specific instructions appended to the agent prompt | No | `""` |
+| `allowed-bot-users` | Allowlisted bot actor usernames (comma-separated) | No | `github-actions[bot]` |
+
+## Required secret
+
+- `GEMINI_API_KEY` — API key for Gemini engine authentication.
+
+## Safe Outputs
+
+- `add-comment` — reply to the issue with research findings

gh-agent-workflows/deep-research/example.yml

@@ -0,0 +1,20 @@
+name: Deep Research
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  actions: read
+  contents: read
+  discussions: write
+  issues: write
+  pull-requests: read
+
+jobs:
+  run:
+    if: >-
+      github.event.issue.pull_request == null &&
+      startsWith(github.event.comment.body, '/research')
+    uses: elastic/ai-github-actions/.github/workflows/gh-aw-deep-research.lock.yml@v0
+    secrets:
+      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}