---
name: search-first
description: Research existing solutions before writing custom code. Checks npm/PyPI/MCP/GitHub for packages, then decides between Adopt, Extend, Compose, or Build.
disable-model-invocation: true
argument-hint: "[feature or problem to research]"
---

# Search Before Building

Research existing solutions for: `$ARGUMENTS`

## Context

Project dependencies:
!`cat package.json 2>/dev/null | jq '.dependencies // {} | keys' 2>/dev/null || echo "No package.json"`

Project tech stack:
!`cat RECOMMENDATIONS.md 2>/dev/null | head -30 || echo "No RECOMMENDATIONS.md"`

## Steps

### 1. Define the need

Clarify what exactly is needed:
- **Problem statement**: What problem does this solve?
- **Requirements**: Must-haves vs nice-to-haves
- **Constraints**: License, bundle size, browser support, security

### 2. Search for existing solutions

Search in order of preference:

1. **Already in project** — Check if a dependency already solves this:
   - Read `package.json` / `requirements.txt` / `go.mod`
   - Search codebase for similar implementations
2. **Package registries** — Search npm, PyPI, crates.io, pkg.go.dev
3. **MCP servers** — Check if an MCP server provides this capability
4. **GitHub** — Search for well-maintained repos with the needed functionality
5. **Framework built-ins** — Check if the framework already provides this (e.g., Next.js Image, React Server Actions)

For each candidate, evaluate:

| Criterion | Check |
|-----------|-------|
| Maintenance | Last commit < 6 months, active issues |
| Popularity | Downloads/stars relative to category |
| Bundle size | Check via bundlephobia or equivalent |
| License | Compatible with project license |
| Security | No known CVEs, dependency tree reasonable |
| Types | TypeScript types included or available |
| API quality | Clean API, good docs, follows conventions |

### 3. Decision matrix

Apply this decision framework:

```
┌─────────────────────────────────────────────────────┐
│ Does an existing solution meet ≥80% of requirements? │
└─────────────────────────┬───────────────────────────┘
                          │
              YES ────────┼──────── NO
              │           │         │
              ▼           │         ▼
     Is it well-maintained?       Can you compose
     Is the API acceptable?       2-3 packages to
              │                   cover 100%?
         YES  │  NO                │
          │   │   │           YES  │  NO
          ▼   │   ▼            │   │   │
       ADOPT  │  EXTEND        ▼   │   ▼
              │  (fork/wrap)  COMPOSE  BUILD
              │                        (custom)
```

| Strategy | When | Risk Level |
|----------|------|------------|
| **Adopt** | Solution fits ≥80%, well-maintained, good API | Low |
| **Extend** | Good base but needs customization (wrapper/plugin) | Medium |
| **Compose** | No single solution, but 2-3 packages combine well | Medium |
| **Build** | No viable existing solution, or critical security/performance need | High |

### 4. Report

```markdown
## Research: [Feature]

### Candidates Found
| Package | Downloads | Size | License | Last Updated | Fit |
|---------|-----------|------|---------|-------------|-----|
| ...     | ...       | ...  | ...     | ...         | ... |

### Recommendation: [ADOPT / EXTEND / COMPOSE / BUILD]

**Selected**: [package name or "custom implementation"]
**Reason**: [why this is the best choice]
**Trade-offs**: [what you give up]

### Implementation Notes
- [How to integrate]
- [Estimated effort]
```

### 5. Anti-patterns to avoid

- **NIH syndrome** — Building custom when a mature solution exists
- **Dependency hoarding** — Adding a package for a 5-line function
- **Popularity bias** — Choosing the most popular, not the best fit
- **Stale research** — Not checking if a previously rejected package has improved
- **Ignoring composition** — Not considering that 2 small libraries > 1 bloated one