/search-first — Research Before You Code
Systematizes the "search for existing solutions before implementing" workflow.
Always run this before writing non-trivial code that might already be solved.
Workflow
1. NEED ANALYSIS → Define what's needed, language/framework constraints
2. SEARCH → Repo → packages → MCP/skills → web
3. EVALUATE → Score candidates against decision matrix
4. DECIDE → Adopt / Extend / Compose / Build inline / Skip
5. IMPLEMENT → Minimal code, no reinvention
Step 1 — Need Analysis
Before searching, state clearly:
- What capability is needed (one sentence)
- Language and framework in use
- Any hard constraints (license, no new deps, size budget, etc.)
Step 2 — Search (in this order)
2a. Check the repo first
Does this already exist in the codebase?
- Search for relevant function/class names in existing modules
- Check
requirements.txt / pyproject.toml / package.json — the dep may already be installed
2b. Search package registries
Use web_search to find candidates:
- Python:
web_search("pypi <capability> python") or "<capability> python library site:pypi.org"
- Node:
web_search("npm <capability> javascript")
- Prioritize packages with: recent commits, high download counts, active issue tracker
2c. Check available MCP servers and skills
- Scan the
available_skills list in the current context — a skill may already cover this
- Check connected MCP servers (visible in Settings → Integrations) — an integration may provide the capability natively
2d. Web search for reference implementations
web_search("<capability> best library <language> <year>") — look for recent comparisons, awesome lists, or authoritative recommendations.
Step 3 — Evaluate candidates
Score each candidate on:
| Criterion |
What to check |
| Functionality |
Does it cover the full need, or just part? |
| Maintenance |
Last commit < 12 months? Open issues responded to? |
| Community |
Download count, GitHub stars, Stack Overflow presence |
| Docs |
README quality, examples, API reference |
| License |
MIT/Apache = safe; GPL = check; no license = avoid |
| Dependencies |
Does it pull in a large transitive tree for a small feature? |
Step 4 — Decision matrix
| Signal |
Action |
| Exact match, well-maintained, permissive license |
Adopt — install and use directly |
| Partial match, good foundation |
Extend — install + write thin wrapper |
| Multiple weak matches |
Compose — combine 2–3 small packages |
| Nothing suitable, but need is real |
Build — write custom, informed by research |
| Trivial to implement (< ~20 lines), any package is overkill |
Build inline — no dependency needed |
| Cost of dependency exceeds benefit |
Skip — reconsider whether the feature is necessary |
Step 5 — Implement
- Adopt/Extend/Compose: install the package, write the minimal glue code, document why it was chosen
- Build: apply elite-coder delivery standards — complete, typed, error-handled
- Build inline: keep it small; if it grows beyond ~30 lines, reconsider whether a package is warranted
Search shortcuts by category
Verify currency before recommending — these reflect common choices as of early 2026.
Python / ML
- HTTP clients →
httpx (async-native, retries built-in)
- Validation →
pydantic (v2 preferred)
- Data processing →
polars (fast), pandas (ecosystem)
- Document parsing →
pdfplumber, unstructured, mammoth
- CLI →
typer, click
JavaScript / TypeScript
- HTTP → native
fetch + ky for retries/hooks
- Validation →
zod
- Testing →
vitest (modern), jest
- Markdown →
remark, unified
Dev tooling
- Linting (Python) →
ruff (replaces pylint + flake8)
- Linting (JS) →
eslint
- Formatting →
black / prettier
- Pre-commit →
pre-commit
Examples
Example 1: "Add dead link checking"
Need: Check markdown files for broken links
Search: web_search("markdown dead link checker npm")
Found: textlint-rule-no-dead-link (score: 9/10, active, MIT)
Decision: ADOPT
Result: npm install + config — zero custom code
Example 2: "Add resilient HTTP client"
Need: HTTP client with retries and timeout handling (Python)
Search: web_search("python http client retries 2025")
Found: httpx has built-in retry support via transport layer
Decision: ADOPT
Result: httpx already in pyproject.toml — no new dep needed
Example 3: "Validate config files against a schema"
Need: Validate project JSON configs against a schema (Node)
Search: web_search("json schema validator cli npm")
Found: ajv-cli (score: 8/10) — validates but needs a schema file
Decision: EXTEND — install ajv-cli, write project-specific schema
Result: 1 package + 1 schema file, no custom validation logic
Example 4: "Format a duration as human-readable string"
Need: Convert seconds to "2h 15m 30s" string (Python)
Search: pypi search → nothing worth the dependency
Decision: BUILD INLINE — 12-line utility function, no package needed
Result: Custom function in utils.py, zero new dependencies
Anti-patterns
- Jumping to code: writing a utility without checking if one exists
- Ignoring existing deps: not checking if the package is already installed
- Stale shortcuts: recommending a library without verifying it's still maintained
- Over-customizing: wrapping a library so heavily it loses its benefits
- Dependency bloat: pulling in a large package for a feature coverable in 15 lines
1---2name: search-first3description: Enforce a research-before-coding workflow — search for existing tools, libraries, and patterns before writing custom code. Use this skill whenever the user asks to add functionality, integrate a new capability, create a utility or helper, or add a dependency. Trigger on phrases like "add X functionality", "integrate X", "I need a library for", "write a helper to", "implement X from scratch", or any time you're about to write non-trivial code that might already exist as a package or tool. When in doubt, search first — reinventing a solved problem is never the right call.4---56# /search-first — Research Before You Code78Systematizes the "search for existing solutions before implementing" workflow.9Always run this before writing non-trivial code that might already be solved.1011---1213## Workflow1415```161. NEED ANALYSIS → Define what's needed, language/framework constraints172. SEARCH → Repo → packages → MCP/skills → web183. EVALUATE → Score candidates against decision matrix194. DECIDE → Adopt / Extend / Compose / Build inline / Skip205. IMPLEMENT → Minimal code, no reinvention21```2223---2425## Step 1 — Need Analysis2627Before searching, state clearly:28- What capability is needed (one sentence)29- Language and framework in use30- Any hard constraints (license, no new deps, size budget, etc.)3132---3334## Step 2 — Search (in this order)3536### 2a. Check the repo first37Does this already exist in the codebase?38- Search for relevant function/class names in existing modules39- Check `requirements.txt` / `pyproject.toml` / `package.json` — the dep may already be installed4041### 2b. Search package registries42Use `web_search` to find candidates:43- Python: `web_search("pypi <capability> python")` or `"<capability> python library site:pypi.org"`44- Node: `web_search("npm <capability> javascript")`45- Prioritize packages with: recent commits, high download counts, active issue tracker4647### 2c. Check available MCP servers and skills48- Scan the `available_skills` list in the current context — a skill may already cover this49- Check connected MCP servers (visible in Settings → Integrations) — an integration may provide the capability natively5051### 2d. Web search for reference implementations52`web_search("<capability> best library <language> <year>")` — look for recent comparisons, awesome lists, or authoritative recommendations.5354---5556## Step 3 — Evaluate candidates5758Score each candidate on:5960| Criterion | What to check |61|---|---|62| Functionality | Does it cover the full need, or just part? |63| Maintenance | Last commit < 12 months? Open issues responded to? |64| Community | Download count, GitHub stars, Stack Overflow presence |65| Docs | README quality, examples, API reference |66| License | MIT/Apache = safe; GPL = check; no license = avoid |67| Dependencies | Does it pull in a large transitive tree for a small feature? |6869---7071## Step 4 — Decision matrix7273| Signal | Action |74|---|---|75| Exact match, well-maintained, permissive license | **Adopt** — install and use directly |76| Partial match, good foundation | **Extend** — install + write thin wrapper |77| Multiple weak matches | **Compose** — combine 2–3 small packages |78| Nothing suitable, but need is real | **Build** — write custom, informed by research |79| Trivial to implement (< ~20 lines), any package is overkill | **Build inline** — no dependency needed |80| Cost of dependency exceeds benefit | **Skip** — reconsider whether the feature is necessary |8182---8384## Step 5 — Implement8586- **Adopt/Extend/Compose**: install the package, write the minimal glue code, document why it was chosen87- **Build**: apply elite-coder delivery standards — complete, typed, error-handled88- **Build inline**: keep it small; if it grows beyond ~30 lines, reconsider whether a package is warranted8990---9192## Search shortcuts by category9394> Verify currency before recommending — these reflect common choices as of early 2026.9596**Python / ML**97- HTTP clients → `httpx` (async-native, retries built-in)98- Validation → `pydantic` (v2 preferred)99- Data processing → `polars` (fast), `pandas` (ecosystem)100- Document parsing → `pdfplumber`, `unstructured`, `mammoth`101- CLI → `typer`, `click`102103**JavaScript / TypeScript**104- HTTP → native `fetch` + `ky` for retries/hooks105- Validation → `zod`106- Testing → `vitest` (modern), `jest`107- Markdown → `remark`, `unified`108109**Dev tooling**110- Linting (Python) → `ruff` (replaces pylint + flake8)111- Linting (JS) → `eslint`112- Formatting → `black` / `prettier`113- Pre-commit → `pre-commit`114115---116117## Examples118119### Example 1: "Add dead link checking"120```121Need: Check markdown files for broken links122Search: web_search("markdown dead link checker npm")123Found: textlint-rule-no-dead-link (score: 9/10, active, MIT)124Decision: ADOPT125Result: npm install + config — zero custom code126```127128### Example 2: "Add resilient HTTP client"129```130Need: HTTP client with retries and timeout handling (Python)131Search: web_search("python http client retries 2025")132Found: httpx has built-in retry support via transport layer133Decision: ADOPT134Result: httpx already in pyproject.toml — no new dep needed135```136137### Example 3: "Validate config files against a schema"138```139Need: Validate project JSON configs against a schema (Node)140Search: web_search("json schema validator cli npm")141Found: ajv-cli (score: 8/10) — validates but needs a schema file142Decision: EXTEND — install ajv-cli, write project-specific schema143Result: 1 package + 1 schema file, no custom validation logic144```145146### Example 4: "Format a duration as human-readable string"147```148Need: Convert seconds to "2h 15m 30s" string (Python)149Search: pypi search → nothing worth the dependency150Decision: BUILD INLINE — 12-line utility function, no package needed151Result: Custom function in utils.py, zero new dependencies152```153154---155156## Anti-patterns157158- **Jumping to code**: writing a utility without checking if one exists159- **Ignoring existing deps**: not checking if the package is already installed160- **Stale shortcuts**: recommending a library without verifying it's still maintained161- **Over-customizing**: wrapping a library so heavily it loses its benefits162- **Dependency bloat**: pulling in a large package for a feature coverable in 15 lines
Yog-Sotho