Research Deep — Batch Item Research

outline.yaml

fields.yaml

/research

Variables

{topic}

outline.yaml

topic

{outline_dir}

outline.yaml

fields.yaml

{output_dir}

outline.yaml

execution.output_dir

./results

{outline_dir}

{batch_size}

outline.yaml

execution.batch_size

{items_per_agent}

outline.yaml

execution.items_per_agent

{fields_path}

{outline_dir}/fields.yaml

{item_name}

name

outline.yaml

{item_slug}

github_copilot

{output_path}

{output_dir}/{item_slug}.json

Step 1: Locate Outline

*/outline.yaml

• If exactly one is found: read it along with the sibling

  fields.yaml

  . Store the containing directory as

  {outline_dir}

  .
• If multiple are found: list them and ask the user which to use.
• If none found: tell the user to run

  /research

  first and stop.

• Topic:

  {topic}

• Items count: N items
• Batch config:

  {batch_size}

  parallel agents,

  {items_per_agent}

  items each
• Output directory:

  {output_dir}

Step 2: Resume Check

{output_dir}

.json

1. Parse the filename back to an item name (reverse the slug:

   github_copilot.json

   -> match against items list)
2. Run the validation script to check completeness:
   bash

   python3 scripts/validate_json.py -f {fields_path} -j {output_path}

3. If validation passes (exit code 0): mark the item as completed — skip it
4. If validation fails (exit code 1): mark the item as incomplete — include it in the run

• "Found N/{total} completed items. Resuming with {remaining} items."
• List the completed items so the user can verify

Step 3: Batch Execution

• Each agent handles up to

  {items_per_agent}

  items
• Launch up to

  {batch_size}

  agents in parallel per batch

• "Batch {N}/{total_batches}: items [list]. Launch?"

{variables}

references/web-search-guide.md

## Task
Research the following item(s) and output structured JSON.

Topic: {topic}

### Items to Research
{for each item assigned to this agent:}
- name: {item_name}
  description: {item_description}
{end for}

## Field Definitions
Read the field definitions file to understand what data to collect for each item:
{fields_path}

Use all field categories and fields defined in that file. Each item gets its own JSON object with every field populated.

## Research Instructions
- Search for authoritative, current information on each item
- Use 2-3 search query variations per item
- Prefer official sources (project websites, documentation, release announcements)
- Cross-reference claims across multiple sources when possible
- Note publication dates — flag anything older than 12 months

## Output Format
For each item, write a JSON file to its output path:

{for each item:}
- {item_name} -> {output_path}
{end for}

Each JSON file must follow this structure:
```json
{
  "name": "{item_name}",
  "category_name": {
    "field_name": "value",
    "field_name": "value"
  },
  "another_category": {
    "field_name": "value"
  },
  "uncertain": ["field_name_1", "field_name_2"],
  "sources": [
    {"description": "Source description", "url": "https://..."}
  ]
}

Field value rules:

• Populate every field defined in fields.yaml
• If a value cannot be confidently determined, write your best estimate and append "[uncertain]" to the string value
• Add the field name to the top-level "uncertain" array
• All values must be in English
• Use the detail_level from fields.yaml to calibrate response length:
  • brief: single value or short phrase
  • moderate: 1-3 sentences
  • detailed: full paragraph or structured breakdown

Validation

python3 {validate_script_path} -f {fields_path} -j {output_path}

**One-shot example** (single item, topic "AI Coding History"):

Task

Items to Research

• name: GitHub Copilot description: Developed by Microsoft/GitHub, first mainstream AI coding assistant

Field Definitions

Research Instructions

• Search for authoritative, current information on each item
• Use 2-3 search query variations per item
• Prefer official sources (project websites, documentation, release announcements)
• Cross-reference claims across multiple sources when possible
• Note publication dates — flag anything older than 12 months

Output Format

• GitHub Copilot -> /Users/you/ai-coding-history/results/github_copilot.json

{
  "name": "GitHub Copilot",
  "basic_info": {
    "release_date": "2021-06-29",
    "company": "Microsoft / GitHub"
  },
  "technical_features": {
    "underlying_model": "OpenAI Codex (initially), GPT-4 (current)",
    "context_window": "Varies by tier; up to 128k tokens in Copilot Enterprise [uncertain]"
  },
  "uncertain": ["context_window"],
  "sources": [
    {"description": "GitHub Copilot official documentation", "url": "https://docs.github.com/copilot"}
  ]
}

Field value rules:

• Populate every field defined in fields.yaml
• If a value cannot be confidently determined, write your best estimate and append "[uncertain]" to the string value
• Add the field name to the top-level "uncertain" array
• All values must be in English
• Use the detail_level from fields.yaml to calibrate response length:
  • brief: single value or short phrase
  • moderate: 1-3 sentences
  • detailed: full paragraph or structured breakdown

Validation

python3 /Users/you/agent-skills/skills/research-deep/scripts/validate_json.py -f /Users/you/ai-coding-history/fields.yaml -j /Users/you/ai-coding-history/results/github_copilot.json

## Step 4: Monitor and Continue

After launching a batch:

1. **Wait** for all agents in the batch to complete
2. **Collect results**: for each agent, check that its output JSON files exist and pass validation
3. **Handle failures**:
   - If an agent fails entirely (no output): log the item names and add them to a retry list
   - If validation fails after the agent finishes: log which fields are missing/invalid
   - **Retry failed items once** in the next batch. If they fail again, mark them as failed and move on.
4. **Report batch progress**: "Batch {N} complete: {succeeded}/{total} items succeeded."
5. **Launch next batch** (with user approval)

## Step 5: Summary Report

After all batches complete, output:

Research Complete

Results

• Completed: {count} / {total} items
• Failed: {count} items {list names if any}
• Items with uncertain fields: {count}

Uncertain Fields Summary

• {item_name}: {list of uncertain field names} {end for}

Failed Items

• {item_name}: {reason for failure} {end for}

## Step 6: Generate Report

After Step 5's summary (or after resume finds all items already completed), generate a markdown report.

**Ask the user**: "Which fields should appear as summary columns in the table of contents? (Pick from the available fields — e.g. release_date, company, github_stars)"

To help the user choose, scan the completed JSON files and list fields that have short values (single numbers, dates, short strings) — these work well as TOC columns.

Run the report generation script:
```bash
python3 scripts/generate_report.py \
  -f {fields_path} \
  -d {output_dir} \
  -o {outline_dir}/report.md \
  --toc-fields field1,field2,field3

{outline_dir}/report.md

Rules

• NEVER modify

  outline.yaml

  or

  fields.yaml

  — they are read-only inputs
• NEVER skip the user approval step before each batch
• NEVER retry a failed item more than once
• Always run the validation script after writing each JSON — do not mark an item as complete until validation passes
• Write JSON files atomically: write to

  {output_path}.tmp

  first, then rename to

  {output_path}

  after validation passes

Gotchas

• Slug collisions: two items could slug to the same filename (e.g. "C++" and "C" could both become

  c

  ). If detected, append a numeric suffix:

  c.json

  ,

  c_2.json

  .
• Large item counts: if there are 50+ items, warn the user about total agent cost before starting.
• fields.yaml changes: if the user modifies fields.yaml between runs, previously completed items won't have the new fields. The validation script will catch this — those items will be re-researched on resume.