By Research

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/:

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 usable target identifier and campaign directory before doing any retrieval.

1. Target identifier (ASK THIS FIRST) — What is the target? Provide a UniProt accession if available, otherwise common name + organism. Without this, no retrieval is possible.
2. Campaign directory — Where should research outputs land? Default is campaigns/{target}/campaign_{YYYYMMDD}_{nnn}/research/. Confirm the path or let the campaign-manager skill allocate one.
3. Modality preference — VHH / scFv / Fab / de novo? Influences SAbDab scaffold filtering and the design recommendation. If unknown, the skill suggests based on target class.
4. Research depth — Quick / Standard / Deep / UltraDeep? If unspecified, auto-select using the indicator heuristics (PDB/SAbDab/PubMed counts).
5. Therapeutic area or use case — Autoimmune? Oncology? Diagnostics? Narrows the PubMed search and risk assessment.
6. Known prior art to include — Has the user already identified key papers or structures? Add them as seed sources to avoid re-discovery.
7. Time budget — Hard deadline? Sets which phases can be skipped if time runs low (see references/methodology.md Time Management).

Standard Workflow

🚨 MANDATORY: USE THE 8-PHASE PIPELINE EXACTLY AS DEFINED — DO NOT COMBINE OR SKIP PHASES 🚨

The 8-phase pipeline (SCOPE → PLAN → RETRIEVE → TRIANGULATE → SYNTHESIZE → CRITIQUE → REFINE → PACKAGE) is defined in the next section. Each phase has a discrete output written to the campaign directory. After every phase, update research_progress.json before moving on.

Discipline:

• ✅ Write the phase's JSON output before claiming the phase is complete
• ✅ Update research_progress.json after every phase (it is the source of truth for resume)
• ✅ Run RETRIEVE-stage tool calls in parallel where possible (single message, multiple tool calls)
• ❌ Do NOT skip Phase 4 (TRIANGULATE) — without it, downstream confidence values are invented
• ❌ Do NOT skip Phase 6 (CRITIQUE) for non-Quick depths — it catches the failure modes that waste compute
• ❌ Do NOT write research.md from memory after phases finish — it must cite sources.json entries

Research Depth

Auto-select depth based on how well-studied the target is. If uncertain, start with Standard and let quality gates decide whether to iterate.

Indicators for depth selection:

• Quick: >10 PDB structures, >5 SAbDab antibodies, >50 PubMed papers
• Standard: 2-10 PDB structures, 1-5 SAbDab antibodies, 10-50 papers
• Deep: 0-1 PDB structures, 0 SAbDab antibodies, <10 papers
• UltraDeep: 0 PDB structures, 0 SAbDab entries, AND any of: novel organism (not human/mouse), novel modality (bispecific, peptide-protein hybrid), or user explicitly requests "deep dive" / "thorough research"

UltraDeep Mode

UltraDeep triggers when:

• Zero PDB structures for the target
• Zero SAbDab entries
• Novel organism (not human/mouse)
• Novel modality request (e.g., bispecific, peptide-protein hybrid)
• User explicitly requests "deep dive" or "thorough research"

UltraDeep adds the following on top of Deep:

• Cross-species homolog search: Find similar proteins in other organisms with known binders via mcp__by-research__research_find_similar_targets, expanding to orthologs across species
• Molecular docking literature review: Targeted PubMed/bioRxiv search for docking studies on the target or homologs
• Patent landscape scan: PubMed patent filter search to identify prior IP and freedom-to-operate considerations
• 2-3 iterations of Phase 3-7: Retrieve-critique loop runs 2-3 times (vs 1 for Deep) to maximize coverage
• Minimum 20 sources, 5+ HIGH confidence findings required to pass quality gates

8-Phase Research Pipeline

Phase 1: SCOPE

Define the research boundaries before searching anything.

Write research/scope.json to the campaign directory:

{
  "target_name": "TNF-alpha",
  "organism": "Homo sapiens",
  "uniprot_accession": null,
  "therapeutic_area": "Autoimmune / inflammation",
  "modality_preference": "VHH",
  "known_information": ["Homotrimeric cytokine", "Multiple approved antibodies"],
  "gaps_to_fill": ["Novel epitope regions", "VHH-specific binding data"],
  "research_depth": "quick",
  "started_at": "2026-03-23T10:00:00Z"
}

Scope comes from user input and quick heuristics. Do not search databases yet.

Phase 2: PLAN

Create a research strategy based on the scope.

Write research/research_plan.json:

{
  "database_queries": [
    {"database": "UniProt+PDB", "tool": "research_get_target_info", "query": "TNF-alpha"},
    {"database": "PubMed+bioRxiv", "tool": "research_search_prior_art", "query": "TNF-alpha"},
    {"database": "SAbDab", "tool": "research_analyze_known_binders", "query": "TNF-alpha"},
    {"database": "UniProt BLAST", "tool": "research_find_similar_targets", "query": "P01375"}
  ],
  "priority_order": ["structure", "literature", "antibodies", "homologs"],
  "depth_per_source": "standard",
  "estimated_time_minutes": 15
}

Priority: structure data first (most reliable for interface analysis), then literature, then existing binders, then homologs with known binders.

Phase 3: RETRIEVE

Execute all searches. Run tools in parallel where possible:

1. mcp__by-research__research_get_target_info — UniProt protein info + PDB structures
2. mcp__by-research__research_search_prior_art — PubMed + bioRxiv literature
3. mcp__by-research__research_analyze_known_binders — SAbDab antibody database
4. mcp__by-research__research_find_similar_targets — homologs with known binders

Save ALL results to research/sources.json with credibility scores:

Each source entry in sources.json:

{
  "id": "src_001",
  "type": "pdb_structure",
  "credibility": 0.95,
  "identifier": "7S4S",
  "title": "Crystal structure of PD-L1 in complex with VHH",
  "key_findings": ["Interface residues: Y56, R113, A121"],
  "retrieved_from": "research_get_target_info",
  "retrieved_at": "2026-03-23T10:02:00Z"
}

Quality gate: After Phase 3, check source count against depth thresholds. If below minimum, re-run with broader queries (drop "antibody" filter, expand date range).

Phase 4: TRIANGULATE

Cross-validate findings across sources:

• Do structural data (PDB interface residues) match literature claims about binding sites?
• Do known antibody epitopes from SAbDab agree with PubMed-reported epitopes?
• Are binding affinity values consistent across publications?

Assign confidence to each finding:

• HIGH: 3+ independent sources agree
• MEDIUM: 2 sources agree
• LOW: Single source only
• CONTRADICTED: Sources disagree (flag explicitly with both sides)

Write research/validated_findings.json:

{
  "findings": [
    {
      "claim": "Residues Y56, R113 are critical for PD-1 binding",
      "confidence": "HIGH",
      "supporting_sources": ["src_001", "src_003", "src_007"],
      "contradicting_sources": [],
      "notes": ""
    }
  ],
  "contradictions": [],
  "summary": "12 findings: 5 HIGH, 4 MEDIUM, 3 LOW, 0 CONTRADICTED"
}

Phase 5: SYNTHESIZE

Structure findings into a coherent narrative covering:

1. Target overview — function, structure, therapeutic relevance
2. Known binders — existing antibodies/nanobodies from SAbDab + literature
3. Epitope analysis — consensus hotspot residues, interface character
4. Design strategy — recommended modality, scaffolds, campaign tier
5. Risk assessment — target difficulty, expected hit rate, key risks

This is the first draft of the research report. Write it as structured prose with inline citations (e.g., "[src_001]").

Phase 6: CRITIQUE

Challenge the synthesis using three distinct review personas. Each persona applies a different lens to the research. The critique output must label every concern with the persona that raised it (e.g., [Skeptical Practitioner], [Adversarial Reviewer], [Implementation Engineer]).

Persona 1: Skeptical Practitioner

Challenges evidence quality and reproducibility:

• Would this replicate? Are the key binding studies based on single experiments or independent replication?
• Is the crystal structure resolution good enough? (>3.0 A structures may have unreliable interface contacts)
• Are we extrapolating from too few data points? (e.g., one mutagenesis study defining the entire epitope)
• Has this epitope actually been validated experimentally, or is it only computationally predicted?
• Are the reported affinity values (Kd, IC50) from comparable assay formats?

Persona 2: Adversarial Reviewer

Attacks logical coherence and reasoning gaps:

• Do the SAbDab results contradict the literature claims? (e.g., known antibodies binding different epitopes than claimed consensus)
• Is the recommended scaffold justified by evidence or just popular? (e.g., defaulting to caplacizumab without target-specific rationale)
• Are there alternative interpretations of the structural data? (e.g., crystal packing artifacts vs true biological interfaces)
• What is the weakest link in the reasoning chain from evidence to design recommendation?
• Have we cherry-picked supportive studies while ignoring contradictory ones?

Persona 3: Implementation Engineer

Questions practical feasibility within the BY toolchain:

• Can BoltzGen actually handle this epitope topology? (e.g., concave pockets, disordered loops, glycosylated surfaces)
• Is the compute budget sufficient for the target difficulty? (novel targets may need Exploratory tier, not Standard)
• Are the recommended scaffolds available in the BoltzGen template library? (check against known VHH/Fab scaffold sets)
• What is the fallback if this approach fails? (alternative modality, different scaffolds, or relaxed hotspot constraints)
• Are there known failure modes for similar targets in the literature?

Critique Output

Write research/critique.json:

{
  "concerns": [
    {
      "persona": "Skeptical Practitioner",
      "concern": "Primary epitope mapping based on single mutagenesis study (src_004)",
      "severity": "HIGH",
      "affected_findings": ["finding_003"],
      "resolution": "Search for independent validation of residues Y56, R113"
    },
    {
      "persona": "Adversarial Reviewer",
      "concern": "SAbDab antibodies bind loop region, contradicting our beta-sheet epitope recommendation",
      "severity": "CRITICAL",
      "affected_findings": ["finding_001", "finding_005"],
      "resolution": "Re-examine epitope consensus, consider both regions"
    },
    {
      "persona": "Implementation Engineer",
      "concern": "Target has N-linked glycosylation at N78 adjacent to proposed hotspots",
      "severity": "MEDIUM",
      "affected_findings": ["finding_002"],
      "resolution": "Check if BoltzGen models glycans; if not, shift hotspots away from N78"
    }
  ],
  "critical_gaps": [],
  "summary": "3 concerns raised: 0 CRITICAL, 1 HIGH, 1 MEDIUM, 1 LOW"
}

Severity levels:

• CRITICAL: Fundamental flaw that could invalidate the design strategy. Requires return to Phase 3.
• HIGH: Significant gap that weakens confidence. Should be addressed in Phase 7.
• MEDIUM: Notable concern worth documenting. Address if feasible in Phase 7.
• LOW: Minor issue for awareness. Document in the final report's Uncertainties section.

If the critique identifies any CRITICAL concerns, return to Phase 3 for targeted retrieval. "Critical gap" = a finding rated HIGH confidence that lacks structural validation, or a design recommendation based only on LOW confidence findings.

Phase 7: REFINE

Address critique findings:

• Run additional targeted searches to fill gaps
• Strengthen weak claims with additional sources
• Explicitly note remaining uncertainties (do not hide them)
• Update confidence levels in validated_findings.json
• Add new sources to sources.json

Phase 8: PACKAGE

Write final outputs to the campaign directory:

1. research/research.md — formatted report (see Output Format below)
2. research/recommended_hotspots.json — residue list for the design agent
3. research/design_recommendation.json — modality, scaffolds, tier, parameters
4. Update campaign state with research summary

Anti-Drift Checkpoints

After completing each phase, write progress to research/research_progress.json:

{
  "campaign_id": "tnf_alpha_20260323_001",
  "current_phase": 3,
  "completed_phases": [1, 2],
  "phase_outputs": {
    "1": "scope.json",
    "2": "research_plan.json"
  },
  "sources_count": 12,
  "quality_gate_passed": true,
  "research_depth": "standard",
  "started_at": "2026-03-23T10:00:00Z",
  "last_checkpoint": "2026-03-23T10:05:00Z"
}

Resuming from checkpoint: If context is compacted mid-research, read research/research_progress.json first. Load all phase outputs listed in phase_outputs. Continue from the phase after the last completed one.

Short task cycles matter: each phase is a discrete, reviewable step. Do not combine phases or skip checkpoints. The checkpoint file is the source of truth for progress.

Quality Gates

For detailed credibility scoring and confidence criteria, read references/quality-gates.md.

Output Format

research.md structure

# Research Report: {Target Name}

## Executive Summary
(2-3 sentences: what the target is, what's known, what we recommend)

## Target Profile
- Name: {name}
- Organism: {organism}
- UniProt: {accession}
- PDB entries: {ids with resolution}
- Function: {brief description}
- Therapeutic relevance: {indication areas}

## Known Binders
| Source | Type | PDB | Epitope Region | Affinity | Reference |
|--------|------|-----|---------------|----------|-----------|
(Table of existing antibodies from SAbDab + literature)

## Epitope Analysis
### Consensus Hotspots
| Residue | AA | Classification | Confidence | Sources |
|---------|-----|---------------|------------|---------|
(Hotspot residues with type and evidence level)

### Interface Character
(Hydrophobic/polar balance, pocket depth, accessibility)

## Design Recommendation
- Modality: VHH / scFv / De novo
- Scaffolds: {recommended with rationale}
- Tier: {preview/standard/production with rationale}
- Estimated designs: {num}
- Hotspot residues: {list in entities YAML range notation}

## Risk Assessment
- Target difficulty: {well-studied / moderate / novel}
- Expected hit rate: {range based on campaign-manager baselines}
- Key risks: {list with mitigation strategies}

## Uncertainties
(Explicitly list what we do NOT know and what remains unvalidated)

## References
[src_001] PDB 7S4S — Crystal structure of...
[src_002] PMID 12345678 — Smith et al. (2024)...
(Numbered citations matching inline references)

recommended_hotspots.json

{
  "target": "TNF-alpha",
  "pdb_id": "7S4S",
  "target_chain": "A",
  "hotspots": [
    {"residue": 56, "aa": "Y", "classification": "polar_anchor", "confidence": "HIGH"},
    {"residue": 113, "aa": "R", "classification": "salt_bridge", "confidence": "HIGH"}
  ],
  "range_notation": "A56-A58,A113,A121-A125",
  "source_ids": ["src_001", "src_003"]
}

design_recommendation.json

{
  "target": "TNF-alpha",
  "modality": "VHH",
  "protocol": "nanobody-anything",
  "scaffolds": ["caplacizumab", "ozoralizumab"],
  "tier": "standard",
  "num_designs_per_scaffold": 5000,
  "budget": 50,
  "rationale": "Well-studied target with multiple VHH co-crystals...",
  "estimated_hit_rate": "20-40%",
  "estimated_time_hours": 2,
  "research_source_ids": ["src_001", "src_002", "src_005"]
}

MCP Tools Available

Research-specific (by-research server)

• research_search_prior_art(target_name, max_results) — PubMed + bioRxiv
• research_get_target_info(target) — UniProt + PDB combined query
• research_analyze_known_binders(target_name, max_structures) — SAbDab
• research_find_similar_targets(uniprot_accession, max_results) — UniProt homolog search

Database tools (for deep dives)

• 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

For database tool usage patterns, see the by-database skill.

Memory Persistence

Session artifacts (campaign directory)

All files go under campaigns/{target}/campaign_{date}_{id}/research/:

Project memory (.claude/memory/)

After completing research, persist target-specific insights that may help future conversations: novel findings about the target, successful design strategies for similar targets, or corrections to commonly misunderstood target biology.

Anti-Hallucination Rules

These are non-negotiable:

• NEVER fabricate PDB IDs, UniProt accessions, PMIDs, or DOIs
• NEVER invent binding affinity values (Kd, IC50, EC50)
• NEVER claim a crystal structure exists without PDB verification
• NEVER present computational predictions as experimental facts
• If a search returns no results, say "no data found" — do not guess
• All claims in research.md must trace to a source in sources.json
• Flag computational predictions explicitly: "predicted (AlphaFold)" vs "experimental (X-ray)"

For detailed methodology including database priority, query construction, and cross-validation rules, read references/methodology.md.

When Scripts Fail

This skill ships two scripts (scripts/research_report_template.md and scripts/summarize_research.py). If they fail, follow the standard hierarchy:

1. Fix and Retry (90%) — Most failures are a missing dependency or wrong path.
   • summarize_research.py only depends on Python stdlib (json, argparse, pathlib). If it errors, check the input JSON path and run again.
   • The template is a static markdown file — copy it, fill it, save.
2. Modify Script (5%) — Edit the script in place if the report layout needs an extra section or the summary needs a new field. Keep the CLI signature stable.
3. Use as Reference (4%) — If the campaign needs a substantially different report format, read the template, adapt the structure inline, but still cite sources.json entries.
4. Write from Scratch (1%) — Only if the 8-phase outputs cannot be reconciled with the template (rare). Document why in research/notes.md.

If the MCP retrieval tools fail (Phase 3), fall back per the database fallback chain in CLAUDE.md: research_* MCP → by-pdb/by-uniprot/by-sabdab MCP → PubMed/bioRxiv → WebSearch. Never silently substitute web search for structured databases.

Common Issues

Best Practices

1. 🚨 CRITICAL: Always run Phase 1 (SCOPE) before any retrieval. Skipping scope leads to scope creep and wasted MCP calls.
2. ✅ REQUIRED: Update research_progress.json after every phase. It is the only resilient resume mechanism.
3. ✅ REQUIRED: Cite every claim in research.md with a [src_XXX] reference. Phase 8 gate enforces this; do not bypass.
4. ✅ Run Phase 3 retrieval tools in parallel (single message, multiple MCP calls) — saves 60-80% wall time.
5. ✅ Prefer UniProt accession over common name when calling research_get_target_info — disambiguates species.
6. ✅ Label every computational source explicitly ("predicted (AlphaFold)") — never present as experimental.
7. ✅ Use the Implementation Engineer persona in Phase 6 to catch BoltzGen-specific topology issues (glycans, disordered loops).
8. ❌ Do NOT skip Phase 4 even when you "already know" the findings agree — write them down explicitly.
9. ❌ Do NOT fabricate PDB IDs, UniProt accessions, PMIDs, or affinity values. If a search returns no results, say "no data found."
10. ✨ Optional: After Phase 8, persist novel target insights to .claude/memory/ for reuse in future campaigns on the same target family.

Suggested Next Steps

After completing this skill, chain into these skills in order:

1. by-epitope-analysis — consumes recommended_hotspots.json and runs deeper structural analysis on the proposed hotspot window (SASA, conservation, druggability). Use this whenever the design will target a specific epitope region.
2. by-campaign-manager — consumes design_recommendation.json and writes campaign_plan.md with budget, scaffolds, fold validation criteria, and submission plan. Required before any compute is committed.
3. by-hypothesis-debate (optional) — if the research yielded multiple viable design strategies, run a hypothesis debate before locking in the modality.
4. by-design-workflow — orchestrates the full Research → Plan → Approve → Design → Screen → Rank pipeline; this skill is its Research stage.

The chain works because each downstream skill expects exactly the JSON shapes this skill writes. Bypassing this skill and writing the JSON files by hand is permitted only when a validated target report already exists.

Related Skills

Upstream (run before this):

• by-session — initializes the BY project, ensures campaign directory exists.

Downstream (run after this):

• by-epitope-analysis — deeper structural hotspot characterization.
• by-campaign-manager — converts research into a budgeted campaign plan.
• by-design-workflow — orchestrates the full design pipeline.

Alternative / complementary:

• by-database — direct database queries for one-off lookups without the 8-phase overhead.
• by-knowledge — project knowledge graph for cross-campaign learnings on similar targets.
• by-hypothesis-debate — adversarial strategy selection when multiple design paths are viable.

References

Detailed documentation:

• references/methodology.md — database priority, query construction, cross-validation rules, anti-hallucination details, time management.
• references/quality-gates.md — credibility scoring, confidence levels, minimum thresholds by depth, gate failure actions.
• references/literature-search-strategy.md — search strategy by organism/protein class, database-first decisions, query patterns, confidence tiering.
• references/checkpoint-recovery.md — checkpoint format, resume protocol, invalidating downstream phases when upstream findings change.

Scripts:

• scripts/research_report_template.md — fillable markdown template covering all 8 phases.
• scripts/summarize_research.py — CLI that reads 8-phase checkpoint outputs and writes a one-page markdown summary for inclusion in campaign_plan.md.

External documentation:

• PDB: https://www.rcsb.org/
• UniProt: https://www.uniprot.org/
• SAbDab: https://opig.stats.ox.ac.uk/webapps/sabdab-sabpred/
• PubMed: https://pubmed.ncbi.nlm.nih.gov/
• bioRxiv: https://www.biorxiv.org/