research-en/README.md

# research-en

Claude Code skill bundle for **structured, resumable, parallel deep research**. Five user-invocable slash commands take a topic from a back-of-the-envelope idea to a finished Markdown report, with web search, per-item parallel agents, JSON validation, and field-by-field coverage checks.

English variant. The bundle ships five skills that share a single project directory layout (`./{topic_slug}/`) and YAML/JSON contract.

## Pipeline

```
/research <topic>           →  outline.yaml + fields.yaml
        ↓
/research-add-items         (optional, supplement items)
/research-add-fields        (optional, supplement fields)
        ↓
/research-deep              →  results/*.json  (one per item, parallel agents)
        ↓
/research-report            →  generate_report.py + report.md
```

## Skills

| Skill | Trigger | What it does |
|-------|---------|--------------|
| `research` | `/research <topic>` | Step 1 — generate initial item list + field framework from model knowledge; Step 2 — launch 1 background web-search-agent to supplement; Step 3 — merge user's existing fields if any; Step 4 — write `outline.yaml` (items + execution config) and `fields.yaml` (field defs with `detail_level: brief|moderate|detailed`). |
| `research-add-items` | `/research-add-items` | Append new research objects to `outline.yaml` (user input + optional web search), dedup, in-place update. |
| `research-add-fields` | `/research-add-fields` | Append new field definitions to `fields.yaml` (user input + optional web search), category + `detail_level` confirmed by user. |
| `research-deep` | `/research-deep` | Auto-locate `outline.yaml`, resume from completed JSONs, batch-launch background web-search-agents (`items_per_agent` per agent, `batch_size` parallel), each writes `{output_dir}/{item_slug}.json` per `fields.yaml`, validates with `validate_json.py`. |
| `research-report` | `/research-report` | Read all JSONs + `fields.yaml`, ask which numeric fields to surface in the TOC, generate `generate_report.py` (handles flat/nested JSON, multi-language category mapping, complex-value formatting, uncertain skipping), execute it to produce `report.md`. |

## File contracts

### `outline.yaml`
```yaml
topic: <research topic>
items:
  - name: <item name>
    category: <category>
    description: <brief>
execution:
  batch_size: <parallel agents>
  items_per_agent: <items per agent>
  output_dir: ./results
```

### `fields.yaml`
```yaml
field_categories:
  - category: Basic Info
    fields:
      - name: <field>
        description: <field description>
        detail_level: brief | moderate | detailed
        required: true | false
uncertain: []   # reserved, populated during deep phase
```

### `results/{item_slug}.json`
```json
{
  "name": "...",
  "release_date": "...",
  "underlying_model": "[uncertain]",
  "uncertain": ["underlying_model", ...]
}
```

Both flat (`{"name": ...}`) and nested (`{"basic_info": {"name": ...}}`) layouts are supported throughout.

## Validation

Every deep-research agent finishes with:

```bash
python research/validate_json.py -f <fields.yaml> -j <result.json>
```

`validate_json.py` reports per-file:
- coverage % (covered / defined fields)
- missing required (FAIL if non-empty)
- missing optional, grouped by category
- extra fields not defined in `fields.yaml`

Exit code is non-zero if any required field is missing.

## Installation

Drop this repo into your vault's Claude Code skills directory:

```bash
git clone https://git.lissad.keenetic.name/Pikaliov/research-en.git \
    .claude/skills/research-en
```

Or as a submodule:

```bash
git submodule add https://git.lissad.keenetic.name/Pikaliov/research-en.git \
    .claude/skills/research-en
```

The five skills are auto-discovered on the next Claude Code session. Verify with `/help` — you should see `/research`, `/research-add-items`, `/research-add-fields`, `/research-deep`, `/research-report`.

**Runtime dependency** (for `validate_json.py`):

```bash
pip install pyyaml
```

`research-deep` calls `validate_json.py` via the `~/.claude/skills/research/validate_json.py` path inside its prompt template — adjust if your install location differs.

## File layout

```
research-en/
├── README.md                            — this file
├── research/
│   ├── SKILL.md                         — /research (preliminary)
│   └── validate_json.py                 — JSON ↔ fields.yaml coverage check (PyYAML)
├── research-add-items/SKILL.md          — /research-add-items
├── research-add-fields/SKILL.md         — /research-add-fields
├── research-deep/SKILL.md               — /research-deep (parallel, resumable)
└── research-report/SKILL.md             — /research-report (markdown synth)
```

## Allowed tools per skill

| Skill | Tools |
|-------|-------|
| `research` | Read, Write, Glob, WebSearch, Task, AskUserQuestion |
| `research-add-items` | Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion |
| `research-add-fields` | Bash, Read, Write, Glob, WebSearch, Task, AskUserQuestion |
| `research-deep` | Bash, Read, Write, Glob, WebSearch, Task |
| `research-report` | Read, Write, Glob, Bash, AskUserQuestion |

## Worked example

```text
/research "AI Coding Assistants since 2024"
# → ./ai_coding_assistants/{outline.yaml, fields.yaml}

/research-add-items
# → adds Cursor, Windsurf, Aider, Continue, etc.

/research-deep
# → batch=4 agents, 2 items each → results/*.json
# → validate_json.py runs after each → coverage report

/research-report
# → ask: "Which fields in TOC besides name?" → github_stars, swe_bench_score
# → ./ai_coding_assistants/{generate_report.py, report.md}
```

## Hard constraints (in skill prompts)

- All field values must be in **English** (deep phase).
- Mark uncertain values with `[uncertain]`, list them in trailing `uncertain` array.
- Prompt templates inside `research/SKILL.md` and `research-deep/SKILL.md` are **hard-reproduce**: only `{xxx}` placeholders may be substituted, structure and wording must not be modified.
- Resume support: `research-deep` skips items that already have a JSON file in `output_dir`.
- Batch gating: `research-deep` waits for user approval between batches (interactive).