/research-discover

description: Discover research papers via semantic search with automated gap analysis and PRISMA-compliant documentation
category: research-management
argument-hint: <query> [--preregister] [--citation-network] [--refine-from <session>] [--limit <count>]
allowed-tools: Bash, Read, Write, Grep, Glob
model: claude-sonnet-5

Research Discovery Command

Task

Execute semantic search for research papers, perform automated gap analysis, and generate PRISMA-compliant search strategies. Connects to Semantic Scholar API to find, rank, and analyze academic papers relevant to user query.

When invoked with `/research-discover <query> [options]`:

1. **Validate** search query and parameters 2. **Construct** Semantic Scholar API query with filters 3. **Execute** API search with rate limiting and error handling 4. **Rank** results by relevance, citations, venue tier, and recency 5. **Analyze** gaps in research coverage 6. **Generate** PRISMA-compliant search strategy 7. **Save** results and create acquisition queue

Parameters

• **`<query>`** (required): Research topic or question (natural language, 3-200 characters)
• **`--preregister`** (optional): Generate PRISMA preregistration protocol for systematic reviews
• **`--citation-network`** (optional): Enable citation chaining (forward and backward)
• **`--refine-from <session>`** (optional): Refine previous search (e.g., `--refine-from last`)
• **`--limit <count>`** (optional): Number of results (default: 100, max: 500)
• **`--year-range <YYYY-YYYY>`** (optional): Publication year filter (e.g., `--year-range 2020-2024`)
• **`--venue <type>`** (optional): Filter by venue type (`conference`, `journal`, `all`)

Inputs

• **Search query**: User-provided research question
• **Configuration**: `.aiwg/research/config.yaml` (API keys, rate limits, ranking weights)
• **Previous search** (if --refine-from): `.aiwg/research/discovery/search-results-{session}.json`

Outputs

• **Search results**: `.aiwg/research/discovery/search-results-{timestamp}.json`
• **Search summary**: `.aiwg/research/discovery/search-summary-{timestamp}.md`
• **Search strategy**: `.aiwg/research/discovery/search-strategy.md` (PRISMA-compliant)
• **Gap analysis**: `.aiwg/research/analysis/gap-report-{timestamp}.md`
• **Acquisition queue**: `.aiwg/research/discovery/acquisition-queue.json`

Workflow

Step 1: Validate Query

# Check query length and format
QUERY="$1"
if [ -z "$QUERY" ]; then
  echo "Error: Query cannot be empty"
  echo "Usage: aiwg research discover \"your research topic\""
  exit 1
fi

# Warn if query too broad
WORD_COUNT=$(echo "$QUERY" | wc -w)
if [ "$WORD_COUNT" -lt 3 ]; then
  echo "Warning: Query may be too broad. Consider adding specificity."
  echo "Example: 'OAuth2 security best practices' instead of 'OAuth'"
fi

Step 2: Construct API Query

Build Semantic Scholar API request:

// API query construction
const apiQuery = {
  query: sanitizeQuery(userQuery),
  limit: options.limit || 100,
  fields: [
    'paperId',
    'title',
    'authors',
    'year',
    'venue',
    'citationCount',
    'doi',
    'abstract',
    'url',
    'isOpenAccess'
  ],
  sort: 'relevance',
  ...(options.yearRange && {
    yearRange: parseYearRange(options.yearRange)
  }),
  ...(options.venue && {
    venue: options.venue
  })
};

Step 3: Execute Search with Rate Limiting

**Security Note**: API keys must be loaded from environment variables or secure configuration files, never hardcoded.

bash <<'EOF'
# Load API configuration
API_KEY=$(grep 'semantic_scholar_api_key' .aiwg/research/config.yaml | awk '{print $2}')

# Construct API request
QUERY="OAuth2 security best practices"
LIMIT=100

# Execute with rate limiting (100 req/5 min)
curl -s \
  -H "x-api-key: ${API_KEY}" \
  "https://api.semanticscholar.org/graph/v1/paper/search?query=${QUERY}&limit=${LIMIT}&fields=paperId,title,authors,year,venue,citationCount,doi,abstract,url" \
  | jq . > .aiwg/research/discovery/search-results-$(date +%s).json
EOF

**Error Handling**:

• **429 Rate Limit**: Wait 60 seconds, retry (3 attempts max)
• **500 Network Error**: Exponential backoff (5s, 10s, 20s), retry
• **0 Results**: Suggest query refinement, broader terms, spelling corrections
• **Disk Full**: Abort, display clear error with `df -h` suggestion

Step 4: Rank Results

Apply ranking algorithm (per BR-RF-D-002):

// Ranking weights
const WEIGHTS = {
  relevance: 0.40,    // Semantic similarity to query
  citations: 0.30,    // Impact proxy (log-scaled)
  venueTier: 0.20,    // A*/A/B/C conference/journal ranking
  recency: 0.10       // Publication year (configurable)
};

// Compute composite score
function rankPaper(paper, query) {
  const relevanceScore = computeSemanticSimilarity(paper, query);
  const citationScore = Math.log10(paper.citationCount + 1) / Math.log10(1000); // Normalize
  const venueScore = getVenueTier(paper.venue); // A*=1.0, A=0.8, B=0.6, C=0.4
  const recencyScore = (paper.year - 1990) / (new Date().getFullYear() - 1990);

  return (
    relevanceScore * WEIGHTS.relevance +
    citationScore * WEIGHTS.citations +
    venueScore * WEIGHTS.venueTier +
    recencyScore * WEIGHTS.recency
  );
}

Step 5: Gap Analysis

Identify under-researched topics (per BR-RF-D-003):

// Gap detection algorithm
function detectGaps(papers) {
  // Cluster papers by topic using citation relationships
  const clusters = clusterByCitations(papers);

  // Identify sparse clusters (<5 papers)
  const underResearched = clusters.filter(c => c.papers.length < 5);

  // Flag contradictory findings (>50% disagreement)
  const contradictory = findContradictions(papers);

  // Suggest missing integrations (concepts never co-occurring)
  const missingIntegrations = findMissingCombinations(papers);

  return {
    underResearchedTopics: underResearched.map(c => c.topic),
    contradictoryFindings: contradictory,
    missingIntegrations
  }