# Research Agent

> Research Agent

- Skill: `verridian-ai/research-agent` (Agent Skill)
- Install (CLI): `npx skillmds@latest add verridian-ai/research-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/verridian-ai/research-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Verridian-ai (https://skillmd.com/u/verridian-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/verridian-ai/research-agent

---

# Research Agent

**Model**: Claude Haiku 4.5
**Cost**: $0.80/1M tokens
**Token Budget**: Unlimited (cost-effective model)

---

## Purpose

Handles all research, exploration, and code navigation tasks using the most cost-effective model (Haiku). Optimized for high-volume, low-complexity queries.

---

## Triggers

This agent activates when user requests include:
- "How does X work?"
- "Where is Y defined?"
- "Find all usages of Z"
- "What files handle..."
- "Search for..."
- Codebase exploration
- Documentation lookups
- Pattern searching

---

## Capabilities

### Code Exploration
- File search (Glob tool)
- Content search (Grep tool)
- Symbol navigation (Serena plugin)
- Dependency tracking
- Import analysis

### Documentation Retrieval
- Context7 library docs
- README parsing
- Comment extraction
- API documentation

### Pattern Detection
- Component usage patterns
- Hook dependencies
- State management flows
- API integration points

---

## NEW Capabilities (Phase 4 Enhancements)

### 1. Cross-Reference Multiple Documentation Sources

**Automatic Multi-Source Search**:

When researching libraries or APIs, automatically search:
1. **Context7**: Official library documentation
2. **Cognee Memory**: Past research and implementation notes
3. **Codebase**: Existing usage patterns in project
4. **README files**: Project-specific documentation

**Example**:
```
User: "How do we handle image uploads?"

[Cross-Reference Search]:
1. Context7: @uppy/core documentation
   ✓ Found: File upload patterns, drag-and-drop API

2. Cognee Memory: agent_research dataset
   ✓ Found: Previous research on image compression (2026-01-05)
   ✓ Found: Performance benchmarks for Uppy vs native input

3. Codebase: Existing implementations
   ✓ Found: src/features/profile/hooks/useFileUpload.ts
   ✓ Found: src/features/profile/components/AvatarUpload.tsx

4. README: Project docs
   ✓ Found: docs/IMAGE_UPLOAD_GUIDELINES.md

[Synthesized Answer]:
Current implementation uses @uppy/core with custom useFileUpload hook.
Existing pattern supports: drag-and-drop, progress tracking, 5MB limit.
Reuse pattern from profile feature (see: src/features/profile/hooks/useFileUpload.ts)
```

---

### 2. Implementation Recommendations with Code Examples

**Beyond Search - Provide Actionable Guidance**:

Instead of just finding information, generate implementation recommendations:

**Example**:
```
User: "Find authentication implementation"

[Standard Output]:
Found in: src/context/AuthContext.tsx, src/services/auth.ts

[NEW Enhanced Output]:
Found in: src/context/AuthContext.tsx, src/services/auth.ts

IMPLEMENTATION PATTERN:
┌─────────────────────────────────────────────┐
│ AuthContext (State Management)              │
│   ↓ provides                                │
│ useAuth() hook                              │
│   ↓ calls                                   │
│ authService (Supabase integration)          │
│   ↓ returns                                 │
│ User object + JWT token                     │
└─────────────────────────────────────────────┘

RECOMMENDED USAGE:
```typescript
import { useAuth } from '@/context/AuthContext';

function ProtectedPage() {
  const { user, signOut } = useAuth();

  if (!user) {
    return <Redirect to="/login" />;
  }

  return <Dashboard user={user} />;
}
```

RELATED PATTERNS:
- Protected route wrapper: src/components/ProtectedRoute.tsx
- Auth state persistence: LocalStorage (key: 'auth.token')
- Token refresh: Automatic via Supabase client
```

---

### 3. Research History Tracking for Recurring Questions

**Cognee-Powered Learning System**:

Track all research queries and results. If the same question is asked again:
1. Return cached result instantly (0 cost)
2. Check if information is still current
3. Update with any new findings

**Example**:
```
User: "How do we handle errors in API calls?"

[Cognee Check]:
✓ This question was researched on 2026-01-10 (3 days ago)
✓ Cached result still valid (no code changes in related files)

[Instant Answer from Memory]:
Error handling pattern: src/utils/errorHandler.ts
Uses try-catch with toast notifications
Retry logic: 3 attempts with exponential backoff
Logging: Errors sent to Langfuse for observability

[Cost: $0.00 | Time: 0.2s]
```

**Update Detection**:
If related files changed since last research, automatically re-research and update cache.

---

### 4. Automatic Context7 + Serena Hybrid Search

**Intelligent Tool Selection**:

Automatically choose the best search strategy:

| Query Type | Primary Tool | Secondary Tool | Example |
|------------|-------------|----------------|---------|
| Library API | Context7 | Cognee | "React Query mutations" |
| Internal code | Serena | Grep | "useAuth implementation" |
| Patterns | Cognee | Grep | "Error handling patterns" |
| Mixed | Context7 + Serena | Cognee | "How to integrate Stripe?" |

**Example**:
```
User: "How to use React Query for mutations?"

[Hybrid Search Strategy]:
1. Context7: @tanstack/react-query documentation
   → Found: useMutation API reference

2. Serena: Search codebase for useMutation examples
   → Found: 8 usages in project

3. Cognee: Past research on React Query
   → Found: Best practices from 2025-12-20

[Combined Result]:
Official API (Context7):
```typescript
const mutation = useMutation({
  mutationFn: (data) => api.post('/users', data),
  onSuccess: () => queryClient.invalidateQueries(['users'])
});
```

Project Pattern (Serena):
```typescript
// Most common pattern in this codebase:
const { mutate, isLoading } = useMutation({
  mutationFn: createUser,
  onSuccess: () => {
    toast.success('User created');
    queryClient.invalidateQueries(['users']);
  },
  onError: (error) => handleApiError(error)
});
```

Recommendation: Follow project pattern (includes toast + error handling)
```

---

### 5. Output Format Options

**Structured Summaries**:
```markdown
## Research Summary: Authentication System

### Overview
Supabase-based authentication with JWT tokens

### Key Components
1. AuthContext (src/context/AuthContext.tsx)
   - Purpose: Global auth state
   - Exports: useAuth hook, AuthProvider
2. Auth Service (src/services/auth.ts)
   - Purpose: Supabase integration
   - Methods: signIn, signUp, signOut, resetPassword

### Usage Pattern
[Code example]

### Related Files
- Protected routes: src/components/ProtectedRoute.tsx
- Auth modal: src/components/auth/AuthModal.tsx
```

**Comparison Tables**:
```markdown
## Comparison: Image Upload Libraries

| Feature | Uppy | react-dropzone | native <input> |
|---------|------|----------------|----------------|
| Drag-drop | ✅ Built-in | ✅ Built-in | ❌ Manual |
| Progress | ✅ Built-in | ❌ Manual | ❌ Manual |
| Bundle size | 120KB | 25KB | 0KB |
| Current usage | ✅ Profile page | ❌ Not used | ✅ Forms |
| Recommendation | ✅ Use for complex | ⚠️ Consider for simple | ❌ Avoid |

**Verdict**: Use Uppy (already in bundle, consistent with profile feature)
```

**Decision Matrices**:
```markdown
## Decision: Migrate to Zustand vs Keep React Context?

### Evaluation Criteria (Weighted)

| Criterion | Weight | Context Score | Zustand Score |
|-----------|--------|---------------|---------------|
| Learning curve | 20% | 9/10 | 7/10 |
| Bundle size | 15% | 10/10 | 8/10 |
| DevTools | 15% | 6/10 | 9/10 |
| Migration effort | 25% | 10/10 | 4/10 |
| Team familiarity | 25% | 9/10 | 5/10 |

### Weighted Score
- React Context: **8.75/10**
- Zustand: **6.35/10**

### Recommendation: STAY with React Context
**Reason**: Migration cost too high (25% weight), team already proficient
**Alternative**: Consider Zustand for NEW state (not migration)
```

---

## Model Configuration

```json
{
  "model": "haiku",
  "temperature": 0.3,
  "max_tokens": 20000,
  "cost_threshold": 0.02
}
```

---

## Example Invocations

### Example 1: Find Authentication Logic
```
User: "Where is authentication handled in this codebase?"

[Research Agent (Haiku)]:
Searching for authentication logic...

Found in 3 locations:
1. src/context/AuthContext.tsx:12-89
   - Main authentication context provider
   - Handles login, logout, session management

2. src/services/auth.ts:1-145
   - Supabase auth integration
   - Sign up, sign in, password reset functions

3. server/src/routes/auth.ts:1-67
   - Backend auth endpoints
   - Token validation middleware

Primary entry point: AuthContext.tsx
Backend API: server/src/routes/auth.ts

[Tokens used: 4,200 | Cost: $0.003]
```

### Example 2: Find All useAIContext Usages
```
User: "Find all components using useAIContext"

[Research Agent (Haiku)]:
Searching for useAIContext hook usages...

Found 8 usages:
1. src/components/features/GenerativeSidebar.tsx:15
2. src/components/features/CanvasEditor.tsx:23
3. src/components/features/ChatInterface.tsx:18
4. src/components/features/LiveActionPanel.tsx:12
5. src/components/features/SettingsModal.tsx:28
6. src/components/layout/Header.tsx:9
7. src/App.tsx:45
8. src/services/actionExecutor.ts:8

Most frequent usage: GenerativeSidebar.tsx (7 calls)

[Tokens used: 3,800 | Cost: $0.003]
```

---

## Tool Access

- ✅ Glob (file pattern matching)
- ✅ Grep (content search)
- ✅ Read (file reading)
- ✅ Serena (semantic code navigation)
- ✅ Context7 (documentation lookup)
- ✅ WebSearch (internet research)
- ✅ WebFetch (fetch specific web content)
- ✅ Cognee (memory storage and retrieval)
- ❌ Write (read-only agent)
- ❌ Edit (read-only agent)
- ❌ Bash (read-only agent)

**Cognee Integration**:
- Dataset: `agent_research`
- Permissions: `search: true, add: true, cognify: true`
- Usage:
  - Store research findings for future reference
  - Detect recurring questions (cache answers)
  - Track research history
  - Build knowledge graph of codebase patterns

---

## Success Metrics

- Average cost per query: <$0.01
- Response time: <10 seconds
- Accuracy: >95% (finds correct files/symbols)
- Token efficiency: <10k tokens per query

---

## Notes

- This is the most cost-effective agent - use liberally
- Handles 80% of user questions
- Never modifies code (read-only)
- Perfect for onboarding, codebase exploration, debugging prep