Search-First Skill: Research Before Building

[dean0x]

Summary

Add a search-first skill that enforces researching existing solutions before writing custom code. A 4-phase loop: Need Analysis → Parallel Search → Evaluation → Decision. Inspired by Harness Alpha's search-first workflow pattern.

Motivation

Harness Alpha identifies a common failure mode in AI-assisted development: building custom utilities when battle-tested packages already exist. Their search-first skill enforces a research phase before any implementation.

The Pattern

1. NEED ANALYSIS — What exactly am I trying to build?
   - Core requirement (one sentence)
   - Constraints (performance, size, compatibility)
   - Nice-to-haves vs must-haves

2. PARALLEL SEARCH — Search 4 sources simultaneously:
   - npm/PyPI/crates (package registry)
   - GitHub (popular repos, recent activity)
   - Existing codebase (maybe it's already built)
   - Skills/patterns library (maybe there's a pattern)

3. EVALUATION — For each candidate:
   - Maintenance status (last commit, open issues, bus factor)
   - Bundle size / dependency weight
   - API fit (does it solve the actual need?)
   - Security (known vulnerabilities, audit history)

4. DECISION — One of three outcomes:
   - USE existing package (document why)
   - ADAPT existing code (document what changes)
   - BUILD custom (document why nothing fits)

Why This Matters for DevFlow

Our Coder agent jumps straight to implementation. The Explore/Skimmer phase searches the codebase but doesn't search for external solutions. This leads to:

• Reinventing utilities that npm packages handle better
• Missing well-tested libraries in favor of custom implementations
• Accumulating maintenance burden from custom code

Where It Fits in DevFlow

The skill would be referenced by the Coder agent and activated by ambient mode for BUILD intent:

1. Coder agent: Before implementing a utility function, check if a package exists
2. Ambient BUILD: When the user says "add date formatting" or "implement retry logic," the skill prompts research before implementation
3. Plan phase: Research results inform architecture decisions

Technical Approach

1. Create shared/skills/search-first/SKILL.md

---
name: search-first
description: Research existing solutions before writing custom code. Prevents reinventing the wheel.
allowed-tools: Read, Grep, Glob
---

Skill content would define:

• The 4-phase research loop
• Evaluation criteria for packages (maintenance, size, security, API fit)
• Decision framework (USE / ADAPT / BUILD with justification)
• Anti-patterns: "Don't add a dependency for 5 lines of code"
• Scope: Only triggers for utility-level code, not domain-specific business logic

2. Ambient Router Integration

Add to the BUILD skill selection matrix:

| Intent | Primary Skills | Secondary |
|--------|---------------|-----------|
| BUILD  | test-driven-development, implementation-patterns, search-first | ... |

3. Plugin Assignment

Add to devflow-core-skills plugin (it's a universal pattern, not language-specific).

Scope & Limitations

• Not for business logic: Only applies to utility/infrastructure code where packages commonly exist
• Not blocking: The skill guides research; it doesn't prevent implementation
• Lightweight: ~100 lines of skill content, no agent changes needed
• Additive: Loads alongside existing BUILD skills, doesn't replace them

Effort & Impact

• Effort: Small (one skill file + ambient router update + plugin manifest)
• Impact: Medium — prevents reinventing the wheel, especially in unfamiliar domains
• Risk: None — advisory skill, no enforcement mechanism