---
name: search-first
description: Mandatory research-before-implementation workflow. Before writing ANY new code, search for existing solutions on GitHub, package registries, and documentation. Prevents reinventing the wheel. Triggers automatically on any implementation task. Use when building features, solving problems, or choosing libraries.
---

# Search First — Never Reinvent the Wheel

Before writing any new code, search for existing solutions. This is mandatory, not optional.

## When to Activate

- Any new feature implementation
- Any utility or helper code
- Any integration with external services
- Any data processing pipeline
- Any problem that feels "universal"

## The Rule

If the problem is universal enough that open-source developers have probably solved it, SEARCH FIRST. Especially for:

- Format conversion (video/audio/image/document)
- Media downloading
- File manipulation
- Web scraping/archiving
- Automation scripts
- CLI tools
- API wrappers
- Authentication flows
- Data validation

## Search Workflow

### Step 1: GitHub Search

Search for existing implementations:
- `gh search repos <keywords>` — find repos solving the problem
- `gh search code <pattern>` — find code patterns in public repos
- Look for repos with >100 stars as quality signal

### Step 2: Package Registries

Check if a library already exists:
- PyPI: `pip search` or pypi.org
- npm: npmjs.com
- Look for actively maintained packages (recent commits, responsive issues)

### Step 3: Documentation

Check official docs for the right approach:
- Framework docs (FastAPI, React, etc.)
- Service docs (AWS, GCP, Stripe, etc.)
- Look for official examples and best practices

### Step 4: Evaluate Options

For each candidate solution, assess:

| Criteria | Weight |
|----------|--------|
| Stars/downloads (popularity) | 20% |
| Last commit date (maintenance) | 25% |
| Open issues ratio | 15% |
| Documentation quality | 20% |
| Fits our stack | 20% |

### Step 5: Decide

- **Adopt**: Use the library/tool directly (best case)
- **Fork**: Clone and modify to fit needs (good case)
- **Port**: Translate the approach to our stack (acceptable)
- **Build**: Write from scratch only if nothing exists (last resort)

## When to Skip Search

Only skip if:
- The code is < 10 lines and trivial
- It's project-specific business logic no one else would have
- You've already searched in this session for the same thing
- The user explicitly said "build from scratch"

## Anti-Patterns

- Writing a CSV parser from scratch (use pandas)
- Writing an HTTP client wrapper (use httpx/requests)
- Writing auth middleware (use established libraries)
- Writing date parsing (use dateutil/arrow)
- Writing a web scraper framework (use scrapy/playwright)
- Building a task queue (use celery/bull)

## Output

After searching, report:
```
SEARCH RESULTS:
- Found: [library/repo name] — [what it does]
- Stars: X | Last commit: [date] | Fits: [yes/no]
- Recommendation: [adopt/fork/port/build from scratch]
- Reason: [why this choice]
```