deep-research

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: deep-research
description: Researches a topic using parallel web search agents, then creates or updates a structured markdown playbook with sourced practitioner insights. Auto-invoke when user says "deep research", "research playbook", "create a playbook about", "update playbook", or asks to deeply research a topic and write findings into a document. Do NOT invoke for simple web searches, quick questions, or general research that does not produce a persistent playbook file.
user-invocable: true
argument-hint: "<topic> [--file path.md]"
allowed-tools: Agent, WebSearch, WebFetch, Read, Edit, Write, Glob, Grep, AskUserQuestion
license: MIT
---

# Deep Research Skill

Research the latest practitioner insights, official docs, and community discussion on a topic, then create or update a playbook.

## Step 0: Parse Arguments

The user's input is: `$ARGUMENTS`

**If no arguments**: Display this help and stop:
```
Usage:
  /deep-research swift concurrency
  /deep-research kubernetes cost optimization --file infra-playbook.md
  /deep-research --file existing-playbook.md   (updates all sections)
Playbook is created in your current working directory by default.
```

**Parsing rules** — MUST follow this order:

1. If `$ARGUMENTS` contains `--file <path>`, extract that as the file path. Everything else is the topic.
2. Else if a token ends in `.md` or contains `/`, treat it as the file path. Everything else is the topic.
3. Else treat ALL of `$ARGUMENTS` as the topic. Auto-generate the file path: `<topic-slug>.md` in the current working directory (e.g., "swift concurrency" → `swift-concurrency.md`).

Examples:
- `/deep-research swift concurrency` → topic: "swift concurrency", file: `swift-concurrency.md`
- `/deep-research kubernetes cost optimization --file infra-playbook.md` → topic: "kubernetes cost optimization", file: `infra-playbook.md`
- `/deep-research --file docs/playbook.md` → topic: inferred from existing file, file: `docs/playbook.md`
- `/deep-research docs/react-hooks.md state management` → topic: "state management", file: `docs/react-hooks.md`

## Step 0.5: Clarify Assumptions

Before proceeding, use **AskUserQuestion** if any of these apply:

- **Ambiguous topic**: The topic has multiple common meanings (e.g., "swift", "python", "spring", "agent", "mercury"). Ask which one.
- **Overly broad topic**: The topic is too wide to research well without focus (e.g., "machine learning", "AI safety"). Ask what aspect or audience matters.
- **Missing context that changes results**: The topic implies a specific context the user hasn't stated (e.g., cloud provider, programming language, audience level).
- **Update mode without topic**: If inferring the research focus from an existing file, confirm the inferred focus before launching agents.

Skip this step if the topic is specific and unambiguous.

## Step 1: Read or Create Playbook

**If the target file exists**:
- Read it. Check if it looks like a playbook (has a Sources section or `*Captured:*` date).
- If yes: note all section headings, Sources list, and voice/style. Set `mode = update`.
- If no: warn user — "This file exists but doesn't look like a playbook. Update it anyway, or create a new file?"

**If the target file does not exist**:
- If no topic was given, stop: "New playbook needs a topic. Usage: `/deep-research <topic>`"
- If the parent directory does not exist, create it.
- Set `mode = create`. The research agents will discover the structure.

Tell the user: "Creating playbook at `<absolute path>`" or "Updating playbook at `<absolute path>`".

## Step 2: Determine Research Scope

### `mode = update` (existing playbook):

Identify the playbook's **subject** from its title and section headings.

**With topic**: Launch 2-3 agents researching the topic within the playbook's subject domain. Each agent MUST search from a different angle:
1. Official docs and authoritative sources
2. Community discussion and practitioner blogs
3. (Optional) Social media and recent reports