discovery-agent-spec

Agent Specification: Discovery Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Discovery Agent | | **ID** | research-discovery-agent | | **Purpose** | Search academic databases, rank results by relevance and quality, detect research gaps, and create reproducible search strategies | | **Lifecycle Stage** | Discovery (Stage 1 of Research Framework) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Discovery Agent is the gateway to the Research Framework, responsible for transforming user research queries into comprehensive, ranked result sets. It leverages semantic search via Semantic Scholar API, performs automated gap detection to identify under-researched areas, and documents PRISMA-compliant search strategies for reproducibility. The agent achieves 60%+ time savings compared to manual search by automating query refinement, citation network traversal, and relevance ranking.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | Semantic Search | Execute natural language queries against Semantic Scholar API (200M+ papers) | NFR-RF-D-01 | | Relevance Ranking | Rank results by semantic similarity, citation count, venue tier, and recency | BR-RF-D-002 | | Gap Detection | Identify under-researched subtopics, contradictory findings, and missing integrations | BR-RF-D-003 | | Citation Chaining | Traverse citation networks (forward/backward) to discover related papers | UC-RF-001 Alt-2 | | Query Refinement | Suggest query improvements when results are too broad or narrow | UC-RF-001 Alt-3 | | PRISMA Strategy | Generate reproducible search strategy documents following PRISMA guidelines | NFR-RF-D-08 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Multi-Database Fallback | Query arXiv API when Semantic Scholar results are insufficient | | Result Deduplication | Merge and deduplicate results across databases by DOI/title | | Progress Reporting | Real-time search progress updates for large result sets | | Acquisition Queue Creation | Prepare selected papers for UC-RF-002 (Acquisition) |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | Execute API queries, file operations | Execute | | Read | Access search configuration, previous strategies | Read | | Write | Save search results, strategies, gap reports | Write | | Grep | Search existing research corpus for duplicates | Read | | Glob | Find related research files | Read |

External APIs

| API | Endpoint | Rate Limit | Auth | |-----|----------|------------|------| | Semantic Scholar | `api.semanticscholar.org/graph/v1` | 100 req/5 min | None (API key optional) | | arXiv | `export.arxiv.org/api/query` | 3 req/sec | None | | CrossRef | `api.crossref.org/works` | 50 req/sec | None |

MCP Servers (Optional)

| Server | Purpose | |--------|---------| | `research-mcp` | Enhanced paper metadata retrieval | | `semantic-search-mcp` | Advanced semantic similarity scoring |

4. Triggers

Automatic Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Research Command | User runs `aiwg research search "<query>"` | Execute semantic search | | Gap Analysis Request | UC-RF-009 requests discovery for gap-filling | Execute targeted search | | Workflow Stage | UC-RF-008 Workflow Agent initiates Stage 1 | Execute discovery for workflow |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Direct Search | `aiwg research search "query"` | Basic semantic search | | Preregistered Search | `aiwg research discover --preregister` | PRISMA-compliant systematic review | | Citation Network | `aiwg research search "query" --citation-network` | Include citation chaining | | Refined Search | `aiwg research search "query" --refine-from last` | Refine previous search |

Event Triggers

| Event | Source | Action | |-------|--------|--------| | Corpus Updated | Archival Agent | Check if new papers trigger gap detection | | Quality Threshold Not Met | Workflow Agent | Discover additional sources |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Search Query | String (3-200 chars) | User command | Non-empty, sanitized | | Publication Year Range | Integer pair (YYYY-YYYY) | Optional flag | Valid years, start <= end | | Result Limit | Integer (1-500) | Optional flag `--limit` | Within API limits | | Venue Filter | Enum (conference, journal, all) | Optional flag `--venue` | Valid enum value | | Preregistration Mode | Boolean | Optional flag `--preregister` | N/A | | Previous Search Context | JSON | Optional flag `--refine-from` | Valid search ID |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | Search Results | JSON | `.aiwg/research/discovery/search-results-{timestamp}.json` | Permanent | | Search Strategy | Markdown | `.aiwg/research/discovery/search-strategy.md` | Permanent | | Gap Report | Markdown | `.aiwg/research/analysis/gap-report-{timestamp}.md` | Permanent | | Acquisition Queue | JSON | `.aiwg/research/discovery/acquisition-queue.json` | Until acquired | | Preregistration Protocol | Markdown | `.aiwg/research/discovery/preregistration/{timestamp}-protocol.md` | Permanent |

Output Schema: Search Results JSON

{
  "query": "OAuth2 security best practices",
  "timestamp": "2026-01-25T10:30:00Z",
  "api_version": "semantic-scholar-v1",
  "total_results": 100,
  "filters_applied": {
    "year_range": "2020-2026",
    "venue": "all"
  },
  "papers": [
    {
      "paper_id": "abc123def456",
      "title": "OAuth 2.0 Security Best Practices",
      "authors": ["Smith, J.", "Doe, A."],
      "year": 2023,
      "venue": "ACM CCS",
      "venue_tier": "A*",
      "citations": 42,
      "doi": "10.1145/e