research-deep

Files (1)

• SKILL.md

SKILL.md (first lines)

# Research Deep - Deep Research

## Trigger
`/research-deep [quick|standard|deep] [run-folder-name]`

Both arguments are optional and may appear in either order. `[quick|standard|deep]` sets the per-item search depth; it overrides `execution.depth` in outline.yaml, which in turn overrides the `standard` default. `[run-folder-name]` names the run folder directly, skipping disambiguation in Step 1. Resolve `{depth}`, `{searches}`, and `{fetches}` from this table before launching anything:

| Level | Searches | Fetches | Link depth |
|---|---|---|---|
| `quick` | 3 | 4 | 1 |
| `standard` *(default)* | 8 | 12 | 1 |
| `deep` | 20 | 30 | 2 |

State the resolved level before the first batch: `Depth: deep (20 searches / 30 fetches per item).` A `deep` run over many items is expensive and slow — if the level came from outline.yaml rather than the user typing it, say so and confirm before launching.

## Workflow

### Step 1: Locate Outline
Locate the run folder per `skills/research/LAYOUT.md`'s discovery rule. If the trigger named a run folder, use it directly and skip disambiguation; otherwise disambiguate per LAYOUT.md. Read items list, execution config (including items_per_agent).

### Step 2: Resume Check
- Check completed JSON files in output_dir
- Skip completed items

### Step 3: Batch Execution
- Before the first batch, flip this run's status in `{root}/INDEX.md` from `outline` to `researching`, per LAYOUT.md. A legacy run with no root has no index — skip this silently.
- Batch by batch_size (need user approval before next batch)
- Each agent handles items_per_agent items
- **Host selection rule:** In GitHub Copilot, launch `Web Research Writer`; in Claude Code, launch `web-search-agent`.
- Launch the host-selected agent (background parallel, disable task output)

**Parameter Retrieval**:
- `{topic}`: topic field from outline.yaml
- `{item_name}`: item's name field
- `{item_related_info}`: item's complete yaml content (name + category + description etc.)
- `{output_dir}`: execution.output_dir from outline.yaml (default: ./results), relative to the run folder, never the cwd — per LAYOUT.md
- `{project_dir}`: absolute path to the run folder located in Step 1 (`{run_dir}` in LAYOUT.md). Everything below hangs off it, never off the cwd.
- `{fields_path}`: absolute path to {project_dir}/fields.yaml
- `{output_path}`: absolute path to {output_dir}/{item_name_slug}.json (slugify item_name: replace spaces with _, remove special chars)
- `{depth}` / `{searches}` / `{fetches}`: resolved from the depth table above.
- `{modules}`: `execution.modules` from outline.yaml — a comma-separated module list pinned for this project. If absent, use the literal string `auto`.
- `{validator_path}`: absolute path to `validate_json.py`. Resolve it in this order and use the first that exists:
  1. `<project_root>/.agents/skills/research/validate_json.py`  (Copilot project-local install)
  2. `<project_root>/.claude/skills/research/validate_json.py`  (Claude project-local install)
  3. `~/.agents/skills/research/validate_json.py`  (Copilot user install)
  4. `~/.claude/skills/research/validate_json.py`  (Claude user install)
  If none exists, tell the user the skill is not fully installed and stop; do not write a replacement validator.

**Hard Constraint**: The following prompt must be strictly reproduced, only replacing variables in {xxx}, do not modify structure or wording.

**Prompt Template**:
```python
prompt = f"""## Task
Research {item_related_info}, output structured JSON to {output_path}

## Field Definitions
Read {fields_path} to get all field definitions

## Search Budget
Depth level: {depth}. Hard limits for this item: {searches} WebSearch calls, {fetches} fetches, one logical fetch sequence per URL.
The fetch budget covers every network retrieval attempt -- WebFetch, the crwl/Firecrawl escalation rungs, and the approved reddit_feed.py helper's own requests -- not just native WebFetch calls.
Use WebSearch and WebFetch for all retrieval. Escalate a blocked page through crwl then Firecrawl, and invoke reddit_feed.py for Reddit listings only, exactly per your own tool discipline. No browser automation, no downloads, no cloning, no self-written scripts, no other helper.
Stop when the fields are answered. Mark whatever is still open as [uncertain] rather than spending more budget on it.

## Modules
Modules: {modules}
Read `web-search-modules/ROUTING.md` before any search. If Modules above is `auto`, route per ROUTING.md yourself;
otherwise load exactly the modules named. Either way, state the modules you loaded in your output.

## Output Requirements
1. Output JSON according to fields defined in fields.yaml
2. Mark uncertain field values with [uncertain]
3. Add uncertain array at the end of JSON, listing all uncertain field names
4. Add unreachable array as a sibling to uncertain; each entry has exactly source, url, and reason keys
5. Use reason fetch_failed when a page remains inaccessible after all the escalation available to it, or zero_domain_results when a search constrained to a named domain returns zero URLs on that domain; zero matching-domain URLs are a zero-result finding, not a result set
6. Unreachable entries annotate source provenance only; a field answered through a documented substitute remains answered, not uncertain
7. All field values must be in English
8. Add sources array as a sibling to uncertain and unreachable; each entry has exactly source, url, and fields keys, where fields lists the field names that source supported
9. Record only sources that contributed to an answer, never a page that was opened but informed no field; a source that supported several fields is one entry with several field names, never repeated entries

A populated sources array looks like this:
"sources": [
  {"source": "GitHub", "url": "https://github.com/features/copilot", "fields": ["pricing"]},
  {"source": "TechCrunch", "url": "https://techcrunch.com/2022/06/21/copilot-githubs-ai-powered-programming-assistant-is-now-generally-available/", "fields": ["release_date", "market_share"]}
]

## Output Path
{output_path}

## Validation
After completing JSON output, run validation script to ensure complete field coverage:
python3 {validator_path} -f {fields_path} -j {output_path}
Task is complete only after validation passes.
"""
```

**One-shot Example** (assuming researching GitHub Copilot):
```
## Task
Research name: GitHub Copilot
category: International Product
description: Developed by Microsoft/GitHub, first mainstream AI coding assistant, ~40% market share, output structured JSON to {project_dir}/results/GitHub_Copilot.json

## Field Definitions
Read {project_dir}/fields.yaml to get all field definitions

## Search Budget
Depth level: standard. Hard limits for this item: 8 WebSearch calls, 12 fetches, one logical fetch sequence per URL.
The fetch budget covers every network retrieval attempt -- WebFetch, the crwl/Firecrawl escalation rungs, and the approved reddit_feed.py helper's own requests -- not just native WebFetch calls.
Use WebSearch and WebFetch for all retrieval. Escalate a blocked page through crwl then Firecrawl, and invoke reddit_feed.py for Reddit listings only, exactly per your own tool discipline. No browser automation, no downloads, no cloning, no self-written scripts, no other helper.
Stop when the fields are answered. Mark whatever is still open as [uncertain] rather than spending more budget on it.

## Modules
Modules: auto
Read `web-search-modules/ROUTING.md` before any search. If Modules above is `auto`, route per ROUTING.md yourself;
otherwise load exactly the modules named. Either way, state the modules you loaded in your output.

## Output Requirements
1. Output JSON according to fields defined in fields.yaml

From eristoddle/deep-research-agent, MIT.

More from eristoddle/deep-research-agent