species-research

name: species-research description: Process tree species research queue, run autonomous species research, conduct deep botanical research. Use when user says "process the queue", "research species", "run species research", "research trees", or mentions the research queue. Generates ATOMIC insights (50-80+ per species) across 35 fields. allowed-tools: WebSearch, WebFetch, Read, Grep, Glob, Bash

Treekipedia Species Research Skill

⚠️ CRITICAL: ATOMIC INSIGHT MODEL ⚠️

READ THIS FIRST. DO NOT SKIP.

You MUST generate MULTIPLE SEPARATE insights for fields that contain multiple distinct facts. This is the #1 requirement.

The Rule

For MULTI-INSIGHT FIELDS, create ONE insight per distinct fact:

WRONG vs CORRECT

❌ WRONG (combining everything into one blob):

{
  "claim_type": "cultural_significance",
  "claim_value": "Sacred in Buddhism, Confucianism, Taoism, and Shintoism. Buddhist monks preserved it. Hiroshima survivor trees are symbols of peace. Used in TCM for 5000 years.",
  "confidence": 0.85
}

This is ONE insight containing 5+ facts = WRONG

✅ CORRECT (atomic - one fact per insight):

[
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Sacred in Buddhism - monks preserved species through temple plantings for over 1000 years", "context": "Buddhism", "region": "East Asia"},
    "confidence": 0.95,
    "sources": [{"url": "https://...", "title": "Buddhist temple records", "type": "historical", "credibility": 0.88}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Six trees survived 1945 Hiroshima atomic bomb within 2km of blast center, now symbols of peace", "context": "Hiroshima hibaku jumoku", "region": "Japan"},
    "confidence": 0.98,
    "sources": [{"url": "https://...", "title": "Hiroshima Peace Memorial", "type": "database", "credibility": 0.95}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Leaves used in Traditional Chinese Medicine for memory and circulation for 2000+ years", "context": "TCM", "region": "China"},
    "confidence": 0.88,
    "sources": [{"url": "https://...", "title": "TCM pharmacopoeia", "type": "database", "credibility": 0.85}]
  },
  {
    "claim_type": "cultural_significance",
    "claim_value": {"text": "Sacred tree in Shintoism, planted at temples throughout Japan", "context": "Shintoism", "region": "Japan"},
    "confidence": 0.85,
    "sources": [{"url": "https://...", "title": "Japanese temple guide", "type": "cultural", "credibility": 0.82}]
  }
]

This is 4 insights for 4 distinct cultural facts = CORRECT

Expected Output

A well-researched species should have 50-80+ total insights across 35 fields:

• Single-value fields: ~20 insights (1 each)
• Multi-insight fields: ~30-60 insights (2-6 each)

If you only have ~35 insights (one per field), you are doing it wrong.

API Base URL

Local (on VM): http://localhost:3000 Remote (Djimo / external): https://treekipedia-api.silvi.earth

All examples below use $API as placeholder. Set it before starting:

API="http://localhost:3000"        # on the VM
API="https://treekipedia-api.silvi.earth"  # remote

Adaptive Research Workflow

Mode 1: Queue-driven (preferred for batch)

Pull from queue, research, save, mark complete. Prevents duplicate work across sessions.

STEP 1: Get next species

curl -s $API/research/queue/next

Response: {"queue_id": 1, "taxon_id": "AngMaMyMyRt39690-00", "species_name": "Myrtus communis", ...}

If queue_empty: true, all species are done.

STEP 2: Mark as processing (locks it so other sessions skip it)

curl -s -X POST $API/research/queue/{queue_id}/start

STEP 3: Get research context

curl -s $API/research/{taxon_id}/context

Returns recommended_focus ("full" for first research, "gaps" for re-research), priority_fields, skip_fields, and existing insight count.

STEP 4: Conduct research — web search all 35 fields, build atomic insights (see below).

STEP 5: Save insights

curl -s -X POST $API/research/{taxon_id}/save \
  -H "Content-Type: application/json" \
  -d '{"model_version": "claude-opus-4-5-20251101", "insights": [...]}'

Response: {"success": true, "insights_saved": 73, "average_confidence": 0.873, "version": 1}

STEP 6: Mark complete

curl -s -X POST $API/research/queue/{queue_id}/complete

STEP 7: Loop — go back to STEP 1 until queue is empty.

Mode 2: Direct (for a specific taxon_id)

If ARGUMENTS provides a taxon_id, skip the queue and research that species directly (steps 3-5 only). Useful for one-off research or re-research.

Research Modes (from context endpoint)

The 35 Research Fields

Identity (4 fields)

• popular_common_name - Most widely-used name + regional variants
• etymology - Meaning of scientific name (Latin/Greek roots)
• synonyms - All taxonomic synonyms from POWO/WCVP
• identification_features - Key visual ID features

Ecological (10 fields)

• general_description - 2-4 sentence botanical description
• habitat - MULTI-INSIGHT: One per habitat type
• elevation_ranges - Actual recorded elevations (meters)
• ecological_function - MULTI-INSIGHT: One per ecosystem service
• native_adapted_habitats - MULTI-INSIGHT: One per region
• conservation_status - IUCN + national listings
• compatible_soil_types - Specific soil preferences
• climate_tolerance - Temperature extremes + rainfall requirements
• tolerances - MULTI-INSIGHT: One per tolerance type
• associated_species - MULTI-INSIGHT: One per community type

Morphological (10 fields)

• growth_form - Tree/shrub/multi-stemmed + variations
• leaf_type - Complete leaf description
• deciduous_evergreen - Note climate variation
• flower_color - With flowering season
• fruit_type - Complete fruit/seed info
• bark_characteristics - How bark changes with age
• maximum_height - Maximum + typical range (meters)
• maximum_diameter - DBH measurements (cm)
• lifespan - Typical vs maximum (years)
• maximum_tree_age - Oldest recorded specimen

Stewardship (11 fields)

• stewardship_best_practices - MULTI-INSIGHT: One per practice
• planting_recipes - Detailed planting instructions
• pruning_maintenance - When and how to prune
• disease_pest_management - MULTI-INSIGHT: One per disease/pest
• fire_management - Fire ecology and management
• propagation_methods - All viable methods
• cultural_significance - MULTI-INSIGHT: One per culture/tradition
• agroforestry_use_cases - MULTI-INSIGHT: One per use case
• timber_value - Wood properties and commercial value
• non_timber_products - MULTI-INSIGHT: One per product category
• nutritional_caloric_value - Edible parts and nutrition

Insight JSON Structure

{
  "claim_type": "field_name",
  "claim_value": {
    "text": "The specific fact being claimed",
    "context": "Category within the field (for multi-insight fields)",
    "region": "Geographic scope if applicable"
  },
  "methodology": "extraction",
  "sources": [
    {
      "url": "https://source-url.com/...",
      "title": "Source Title",
      "type": "database|journal|government|cultural|grey_literature",
      "credibility": 0.90
    }
  ]
}

Note: Do NOT include confidence in your insights. The orchestrator calculates evidence-based confidence from your sources automatically.

Search Strategy

Core Searches (every species)

"{species}" POWO OR WCVP taxonomy accepted name
"{species}" IUCN conservation status assessment
"{species}" GBIF distribution native range
"{species}" ecology habitat ecosystem biome
"{species}" morphology height diameter bark leaf flower fruit
"{species}" traditional use ethnobotany medicinal cultural
"{species}" cultivation propagation planting agroforestry
"{species}" timber wood properties uses

Grey Literature

"{species}" filetype:pdf site:.edu OR site:.gov
"{species}" dissertation OR thesis
"{species}" site:fao.org OR site:worldagroforestry.org

Source Credibility Tiers

Key Endpoints ($API = http://localhost:3000 or https://treekipedia-api.silvi.earth)

Remember

1. ATOMIC INSIGHTS - Split multi-value fields into separate insights
2. 50-80+ insights expected per well-documented species
3. If you only have ~35 insights, you're doing it wrong
4. CHECK CONTEXT FIRST - Call $API/research/{taxon_id}/context before researching
5. ADAPT your research based on recommended_focus
6. Don't include confidence - orchestrator calculates it from sources
7. Search HARDER for poorly documented species
8. USE THE QUEUE for batch work — it prevents duplicate effort across sessions