nixos/shared/linked-dotfiles/opencode/skills/research/SKILL.md

---
name: research
description: Use when conducting deep research across any domain - provides citation patterns, concise synthesis techniques, and cross-domain connection strategies
---

# Research Skill

Quick reference for conducting deep research with proper citations, concise output, and novel insights across any domain.

## When to Use This Skill

- Investigating technical topics (APIs, frameworks, algorithms)
- Understanding psychological or human factors
- Exploring creative writing techniques or artistic approaches
- Synthesizing information from multiple disparate sources
- Making connections between different domains
- Gathering authoritative sources for decision-making

**When NOT to use:**
- Simple factual lookups (use direct search instead)
- Code implementation (use coding agents)
- Quick reference checks (use man pages directly)

## Citation Format Reference

### Web Sources
```
<source url="https://example.com/article" title="Article Title">Specific claim or finding from the source</source>
```

### Academic Papers
```
<source url="https://arxiv.org/abs/2210.03629" title="ReAct: Synergizing Reasoning and Acting">Quantitative finding or key insight</source>
```

### Local Files
```
<source url="file:///path/to/file.md" title="filename.md">Code snippet or configuration detail</source>
```

### Man Pages
```
<source url="man://grep" title="grep(1) manual">Command behavior or flag description</source>
```

### Multiple Sources for Same Claim
```
<source url="https://source1.com" title="First Study">Initial finding</source> corroborated by <source url="https://source2.com" title="Second Study">confirming evidence</source>
```

## Output Style Guide

| Good (Concise Paragraphs) | Bad (Bullets/Verbosity) |
|---|---|
| The STORM paper introduces a multi-agent system for comprehensive research. <source>Finding</source>. This approach yields Wikipedia-quality output. | It is important to note that:<br>- STORM uses agents<br>- Perhaps it works well<br>- Furthermore, one might consider... |
| Direct statement with citation. | "It seems that this might be useful..." |
| 2-4 sentence paragraphs. | Wall of text or excessive bullets. |

## ReAct Research Loop

**Pattern for iterative research:**

1. **Thought**: "I need to understand X. Sources to check: Y, Z."
2. **Action**: `curl https://docs.example.com/api` or `man command` or `rg "pattern"`
3. **Observation**: "Found A, B, C. Still missing D."
4. **Thought**: "Need to refine search for D."
5. **Action**: New search with refined query
6. **Observation**: "Now have complete picture."

Repeat until sufficient evidence gathered.

## Making Cross-Domain Connections

### Technique: Analogy Mapping

1. Identify core mechanism in source domain
2. Find parallel structure in target domain
3. Map relationships explicitly
4. Test if analogy reveals new insights

**Example**: ReAct pattern (technical) ↔ Expert problem-solving (psychology)
- Both externalize thinking
- Both enable error detection
- Both reduce cognitive load
- Connection reveals *why* ReAct works

### Technique: Pattern Recognition

Look across sources for:
- Recurring themes or principles
- Shared constraints or trade-offs
- Similar solution approaches
- Common failure modes

### Technique: Contrast Analysis

When sources disagree:
- Identify specific points of tension
- Examine underlying assumptions
- Consider context differences
- Synthesize higher-level insight

## Research Tool Usage

### Web Research
```bash
# Fetch documentation
curl -s https://docs.example.com/api | grep "pattern"

# Download paper
wget https://arxiv.org/pdf/2210.03629.pdf

# Search with specific terms
curl -s "https://api.example.com/search?q=term"
```

### Man Pages
```bash
# Full manual
man grep

# Search within man page
man grep | grep -A 5 "pattern"

# List all man pages for command
man -k search_term
```

### Code/File Research
```bash
# Find implementations
rg "function_name" --type rust

# Search with context
rg "pattern" -A 3 -B 3

# Find files by name
find . -name "*.md" -type f
```

## Common Mistakes

**Mistake: Uncited claims**
```
❌ "The ReAct pattern improves performance significantly."
✅ "The ReAct pattern improves performance significantly. <source>specific metric</source>."
```

**Mistake: Verbose hedging**
```
❌ "It seems that perhaps one might consider that this could potentially..."
✅ "This approach increases success rates by 34%."
```

**Mistake: Bullet point overload**
```
❌ Long lists of disconnected bullets
✅ 2-4 sentence paragraphs that flow coherently
```

**Mistake: Missing cross-domain insights**
```
❌ Only technical analysis without broader connections
✅ "This pattern mirrors cognitive psychology research on expert problem-solving..."
```

**Mistake: No verification step**
```
❌ Output without checking citation coverage
✅ Self-check: Every claim cited? Format correct? Under 500 words?
```

## Output Structure Template

```
[1-2 sentence context establishing the question and why it matters]

[Paragraph 1: First major finding with citations. 2-4 sentences. Focus on one insight.]

[Paragraph 2: Second major finding with citations. Builds on or contrasts with first.]

[Paragraph 3: Cross-domain connection or novel insight. "Interestingly..." or "This pattern mirrors..."]

[Optional Paragraph 4: Practical implications or actionable takeaways if relevant.]

## Sources
1. [Title](URL) - Brief description of what this source provides
2. [Title](URL) - Brief description
```

## Quality Checklist

Before finalizing research output:

- [ ] Every significant claim has source citation
- [ ] Citations use correct XML format with URL and title
- [ ] Writing is direct - no hedging or filler phrases
- [ ] Output uses small paragraphs (2-4 sentences), not bullets
- [ ] Under 500 words for typical queries
- [ ] At least one cross-domain connection identified
- [ ] Multiple perspectives considered (technical, human, business, creative)
- [ ] Bibliography section lists all sources
- [ ] Verification step completed

## Domain-Specific Notes

### Technical Research
Focus on: Implementation details, performance metrics, trade-offs, compatibility, version-specific behavior

### Psychology/Human Factors
Focus on: User studies, cognitive principles, behavioral patterns, accessibility, mental models

### Creative Writing
Focus on: Techniques from literature, stylistic approaches, examples from published works, craft advice from authors

### Science/Research
Focus on: Peer-reviewed sources, methodology, empirical findings, replication status, statistical significance

## Example: Good Research Output

**Query**: How does the ReAct reasoning pattern work?

**Output**:

The ReAct pattern addresses a key limitation in language model task-solving by interleaving reasoning traces with tool actions. <source url="https://arxiv.org/abs/2210.03629" title="ReAct: Synergizing Reasoning and Acting in Language Models">ReAct agents achieve 34% higher success rates on ALFWorld tasks and 10% improvement on HotpotQA compared to baselines</source>. The core mechanism involves explicit Thought-Action-Observation loops where the model verbalizes its reasoning before taking each action, then updates its understanding based on observations.

This architecture mirrors findings from cognitive psychology on expert problem-solving. <source url="file://references/cognitive-science.md" title="Expert Problem Solving Research">Experts externalize their thinking through verbal protocols, which reduces cognitive load by offloading working memory to external representations</source>. By forcing LLMs to "think aloud," ReAct essentially implements this expert strategy in artificial systems.

The practical implication is clear: tasks requiring multi-step reasoning benefit from explicit trace generation. ReAct excels when error recovery matters, since failed actions produce observations that redirect reasoning. For simple, single-step tasks, the overhead isn't justified.

## Sources
1. [ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629) - ICLR 2023 paper introducing the pattern
2. [Expert Problem Solving Research](file://references/cognitive-science.md) - Cognitive science on externalized thinking

---

*Note: This skill is designed for use with the research agent. It provides quick reference patterns for citations, concise synthesis, and cross-domain insights.*