/by-research

id: "skill_bf649c6b31b64e9797f3b685b50f0b77"
name: "by-research"
display-name: "BY Research"
short-description: "Deep academic research for antibody/binder design campaigns with an 8-phase pipeline, quality gates, and persistent memory. Use when starting a new design campaign, investigating a target, searching prior art, or analyzing epitopes."
category: "research"
keywords: "target research, literature review, prior art, epitope analysis, PDB, UniProt, SAbDab, PubMed, bioRxiv, design strategy, scaffold selection, hotspot identification"
version: "1.0"
last-updated: "2026-05-20"
mcp_tools:
  - "mcp__by-research__research_get_target_info"
  - "mcp__by-research__research_search_prior_art"
  - "mcp__by-research__research_analyze_known_binders"
  - "mcp__by-research__research_find_similar_targets"
  - "mcp__by-pdb__pdb_search"
  - "mcp__by-pdb__pdb_fetch_structure"
  - "mcp__by-pdb__pdb_get_chains"
  - "mcp__by-pdb__pdb_interface_residues"
  - "mcp__by-uniprot__uniprot_search"
  - "mcp__by-uniprot__uniprot_fetch_protein"
  - "mcp__by-uniprot__uniprot_get_domains"
  - "mcp__by-uniprot__uniprot_get_variants"
  - "mcp__by-sabdab__sabdab_search_antibodies"
  - "mcp__by-sabdab__sabdab_get_structure"
  - "mcp__by-sabdab__sabdab_cdr_sequences"
  - "mcp__by-sabdab__sabdab_search_by_antigen"

BY Research Skill

Thorough target research before design prevents wasted compute and failed campaigns. This skill defines an 8-phase pipeline that retrieves, validates, and packages research findings with quality gates and anti-drift checkpoints at every stage.

When to Use This Skill

Use this skill when you have:

• ✅ **A protein target name or identifier** (UniProt accession, gene name, PDB ID, or common name)
• ✅ **A new design campaign starting** — research is always step 1 before planning
• ✅ **A need to characterize prior art** — existing antibodies, nanobodies, or designed binders
• ✅ **A target with unknown or partially characterized epitopes** — needs hotspot identification from literature + structure
• ✅ **A need to choose modality or scaffold** — research informs VHH vs scFv vs de novo
• ✅ **An interrupted research session** — resume from `research_progress.json` checkpoint

Do NOT use this skill when:

• ❌ **You already have a validated target report** in the campaign directory → load it instead of re-researching
• ❌ **You are scoring or filtering existing designs** → use `by-scoring` or `by-screening`
• ❌ **You are predicting structure of a known sequence** → use Protenix directly (no literature needed)
• ❌ **You need lab submission logistics** → use `by-deploy-compute` or the lab-submission flow
• ❌ **The user wants ranked design results** → use `by-display` / `results` skill
• ❌ **You need a one-off database lookup** (single PDB fetch) → call the MCP tool directly, no 8-phase overhead

Quick Start

User: "Research TNF-alpha for a nanobody design campaign."

Agent:
  1. Phase 1 SCOPE  → writes research/scope.json (target=TNF-alpha, modality=VHH, depth=quick)
  2. Phase 2 PLAN   → writes research/research_plan.json
  3. Phase 3 RETRIEVE → calls 4 research_* MCP tools in parallel, writes sources.json
  4. Phase 4 TRIANGULATE → writes validated_findings.json
  5. Phase 5 SYNTHESIZE → drafts research.md
  6. Phase 6 CRITIQUE  → 3 personas, writes critique.json
  7. Phase 7 REFINE   → closes gaps, updates sources.json + validated_findings.json
  8. Phase 8 PACKAGE  → writes research.md + recommended_hotspots.json + design_recommendation.json

Expected: 10-15 sources, 3+ HIGH confidence findings, 5-10 hotspot residues,
         design_recommendation.json with modality/protocol/tier ready for campaign-manager.

Inputs

**Required:**

• **Target identifier** (one of):
• Common name (e.g., `"TNF-alpha"`, `"PD-L1"`, `"HER2"`)
• UniProt accession (e.g., `"P01375"`) — most specific, preferred
• Gene name (e.g., `"TNFSF2"`)
• PDB ID (e.g., `"7S4S"`) — auto-derives UniProt
• **Campaign directory** — path under `campaigns/{target}/campaign_{date}_{id}/` where outputs land

**Optional:**

• **Organism** — defaults to `Homo sapiens`. Specify for non-human orthologs.
• **Modality preference** — `VHH` / `scFv` / `Fab` / `de_novo`. Influences scaffold search.
• **Research depth** — `quick` / `standard` / `deep` / `ultradeep`. Auto-selected from indicator heuristics if absent (see depth table).
• **Therapeutic area** — narrows literature search.
• **Known information** — prior facts the user already has; skip redundant retrieval.
• **Existing checkpoint** — `research/research_progress.json` from a paused session.

See `references/literature-search-strategy.md` for query construction by organism/protein class.

Outputs

All outputs go to the campaign directory at `campaigns/{target}/campaign_{date}_{id}/research/`:

| File | Type | Phase | Purpose | |------|------|-------|---------| | `scope.json` | JSON | 1 | Research boundaries (target, organism, modality, depth) | | `research_plan.json` | JSON | 2 | Search strategy, priority order, time budget | | `sources.json` | JSON | 3, 7 | All retrieved sources with credibility scores | | `validated_findings.json` | JSON | 4, 7 | Cross-validated findings with confidence (HIGH/MEDIUM/LOW/CONTRADICTED) | | `critique.json` | JSON | 6 | Multi-persona red team concerns with severity | | `research_progress.json` | JSON | Every | Checkpoint for resume (current phase, completed phases, phase outputs) | | `research.md` | Markdown | 8 | Final formatted report — feeds campaign_plan.md | | `recommended_hotspots.json` | JSON | 8 | Residue list with range notation for design agent | | `design_recommendation.json` | JSON | 8 | Modality, protocol, scaffolds, tier, budget for campaign-manager |

The two **downstream-critical** outputs are `recommended_hotspots.json` (consumed by `by-epitope-analysis`) and `design_recommendation.json` (consumed by `by-campaign-manager`).

Clarification Questions

⚠️ **CRITICAL: ASK THIS FIRST** — confirm you have a usa