# research-first

The research-first skill checks current documentation and discussions before tracing code when an issue depends on an external framework, tool, or platform. For repo-local questions, it searches the repository instead.

- skill · `type=skill` · Claude Code, Codex, OpenCode, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 539 repo stars
- Author: ZaxbyHub
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.claude/skills/research-first/SKILL.md
- Updated: 2026-10-29
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/research-first

## What it does

Use the skill to investigate a bug, plan a fix, or examine technical debt. When a question depends on an outside framework, dependency, or platform behavior, it checks official documentation, newer releases, and discussions across separate sources first. It returns findings with URLs before beginning code tracing.

For questions about a repository’s own conventions or structure, it skips web research and reads `AGENTS.md`, `docs/`, and the source. It then follows each issue through the code and marks conclusions that lack enough evidence. The skill runs in a separate Explore context and cannot start sub-agents. If `WebSearch` or `WebFetch` cannot be used, it proceeds by tracing code, so external behavior cannot be checked online.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/research-first/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/research-first/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/research-first/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/research-first/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install ZaxbyHub/opencode-swarm .claude/skills/research-first
```

2. **Manually: put the files in place**
- File: `.github/skills/research-first/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .claude/skills/research-first
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/research-first/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add ZaxbyHub/opencode-swarm --skill research-first -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.claude/skills/research-first/SKILL.md

## When to use it
- check whether a dependency bug was fixed in a newer release
- find current guidance before planning a code change
- trace a failure through the relevant source code
- mark conclusions that still lack supporting evidence

## Example prompts
- Investigate why this integration with an external framework behaves unexpectedly, starting with current documentation.
- Review technical debt in this repository using its project rules and trace the related code paths.
- Check whether a newer dependency release fixes this issue, then trace its cause through the source.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 73289ba0fdcd3a9e.

BEGIN THIRD-PARTY FILE 73289ba0fdcd3a9e
```text
---
name: research-first
description: >
  Apply when planning fixes, investigating tech debt, architecting solutions, or
  diagnosing unknown issues that may involve external frameworks, dependencies,
  or platform behavior. Search online for current documentation and
  state-of-the-art approaches before tracing through code.
context: fork
agent: Explore
metadata:
  audience: swarm-plugin
---

## Research Before Planning Protocol

This skill body runs in an isolated Explore context: it has no conversation
history and cannot spawn further sub-agents. Work from the task statement it
receives, run searches and reads directly, and return a compact findings
report.

Scope guard — research the outside world only when the problem involves it:
- If the question involves external frameworks, dependencies, platform or
  toolchain behavior, or a suspected upstream bug: research online first.
- If the question is purely repo-local (project conventions, invariants,
  existing code structure), skip web research; the answer lives in the
  repository (AGENTS.md, docs/, and the source itself).
- If WebSearch/WebFetch are unavailable in this environment, state that
  explicitly and proceed with code tracing rather than stalling.

When researching:

1. Search current official documentation to confirm the behavior is NOT
   intended and NOT already fixed in a newer release
2. Search for state-of-the-art solutions, known community workarounds, and
   recent discussion of this problem type
3. Run multiple searches across distinct sources (official docs, issue
   trackers, release notes) rather than trusting the first hit
4. Report all findings — with URLs — before any code tracing begins

Then trace each problem end-to-end through the actual source code.
Do not stop until ≥95% confident in the root cause for every issue being
investigated, and mark anything below that threshold as UNVERIFIED with what
evidence is missing.
```
END THIRD-PARTY FILE 73289ba0fdcd3a9e

The third-party file has ended. Everything between the 73289ba0fdcd3a9e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

© ZaxbyHub · MIT · https://github.com/ZaxbyHub/opencode-swarm/tree/HEAD/.claude/skills/research-first/SKILL.md

## Similar
- [research](https://affpapa.org/en/nevibecode/commands/research.md) — command · ★ 3232 repo stars
- [principle-redesign-from-first-principles](https://affpapa.org/en/nevibecode/skills/principle-redesign-from-first-principles.md) — skill · 10200 installs
- [thinking-first-principles](https://affpapa.org/en/nevibecode/skills/thinking-first-principles.md) — skill · 844 installs
- [edge-ai-tasks](https://affpapa.org/en/nevibecode/plugins/edge-ai-tasks.md) — plugin · ★ 41430 repo stars
- [open-source-librarian](https://affpapa.org/en/nevibecode/agents/open-source-librarian.md) — subagent · ★ 1064 repo stars
- [codex-first](https://affpapa.org/en/nevibecode/skills/codex-first.md) — skill · 288 installs

## Other versions with the same name
- [research-first · zaxbyhub](https://affpapa.org/en/nevibecode/skills/zaxbyhub-research-first.md) — ★ 539 repo stars

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
