Research First

Research-First Workflow

Before writing a single line of code, drafting a document, or designing a process, find the best existing tools, libraries, templates, frameworks, and resources. A 5-minute search saves hours of work and weeks of maintenance.

The Workflow

Step 1: Understand the task and detect existing context (30 seconds)

Clarify:

• Core problem or deliverable
• Constraints (language, framework, budget, timeline, audience, format)
• What's already available. The best recommendation almost always depends on what already exists.

Load the domain-specific context detection from the matching reference:

• Dev tasks -> references/dev.md
• Writing / content tasks -> references/writing.md
• Data / analysis / ML tasks -> references/data.md
• Ops / process / infra tasks -> references/ops.md

If context is clear from the conversation, don't ask - just proceed.

Step 2: Search for existing solutions (the core of this skill)

Run searches in parallel where possible. Breadth first, depth on the best candidates.

2a. Check available MCPs, plugins, and skills (skip for pure writing/content tasks):

• Layer 1 - already connected: if a tool in the current session handles it, use it directly.
• Layer 2 - registries: search_mcp_registry with 2-3 keyword variations. search_plugins for installable plugins. Check Smithery.ai, mcp.run, Glama.ai.
• Layer 3 - community: awesome-mcp-servers on GitHub, punkpeye/awesome-mcp-servers, modelcontextprotocol/servers. GitHub Discussions for real-world reports. Reddit and Hacker News for unfiltered opinions.

Forums beat blogs: developers will say "I tried X and it was terrible because..." - blogs rarely do.

2b. Look for similar open-source projects (do this FIRST when the task is "build a product / system / clone / tool").

Before building anything non-trivial, check if someone has already built something similar that you can:

• Use directly as an open-source alternative to a commercial tool
• Self-host and adapt when the hosted version doesn't fit your constraints
• Fork and extend for missing features (flag license compatibility)
• Learn from as a reference architecture, even if you ultimately build your own

This applies to requests like "build a CRM", "make a Notion clone", "create a job queue", "I want a dashboard tool". Prioritize open-source; include paid alternatives only when clearly the best fit, and flag them explicitly as paid.

Primary searches:

• "open source {category} github", "self-hosted {product}", "{commercial product} open source alternative"
• GitHub: topic:{keyword} (browse at github.com/topics/{topic}) and search in:name,description,topics {keyword} stars:>500
• site:alternativeto.net {product} - filter "Open Source"
• awesome-selfhosted - canonical self-hostable list (15k+ stars)
• openalternative.co - curated OSS alternatives to popular SaaS
• GitHub Trending - what the community is building now

More search patterns and resource lists in references/dev.md.

2c. Web search for tools, libraries, and resources (for the pieces you'll assemble inside your project) - query patterns are domain-specific, see the matching reference file.

2d. Search for reusable patterns and templates - boilerplates, starter repos, document frameworks, analysis notebooks, SOPs. See the domain reference.

Step 3: Evaluate candidates (rigorous validation with bias detection)

For each candidate, verify:

Anti-bias filter. Many "Top 10" blogs rank their own product #1. Mitigations:

• Cross-reference 3+ independent sources. If only one blog promotes it, be skeptical.
• Prioritize objective metrics (stars, downloads, StackOverflow question count) over opinions.
• Prefer neutral sources: Stack Overflow, GitHub trending, npmtrends.com, Reddit/HN threads, official framework docs.
• When in doubt, tell the user. If the best source is the product's own site, say so.

Step 4: Present the recommendation

• Recommended approach: one clear pick with reasoning. Why it fits the existing stack. If a similar open-source project exists, say whether to use it directly, self-host, fork, or just use as reference.
• What it solves: how it addresses the task.
• What we still need to build: remaining custom work (if any).
• Alternatives: 1-2 options with trade-offs. Include similar projects found, commercial alternatives (clearly flagged as paid), and stack-overlap options.
• Free resources found: anything relevant from free-for.dev or similar.

Step 5: Execute with found resources

Only now create. Install/adopt the recommended resource instead of reimplementing. Reference official docs - don't guess APIs. Document the source (URL comment, citation). Domain-specific execution guidance lives in the matching reference file.

Effort calibration

Not every task warrants the full 5-step workflow.

A search that takes longer than the task itself is waste.

What NOT to do

• Don't skip the search and jump to creating, even if you "know" how.
• Don't reimplement a whole product when a similar open-source project already exists. Check awesome-selfhosted, openalternative.co, and GitHub topics before assembling from scratch.
• Don't recommend abandoned projects (12+ months no commits with open critical issues).
• Don't recommend libraries with unpatched CVEs.
• Don't add heavy frameworks when a utility would do.
• Don't spend more than 2-3 minutes searching for a simple task.
• Don't trust a single "Top 10" blog as your only source - cross-reference.
• Don't apply dev metrics (GitHub stars) to non-dev tasks (document templates).

Edge cases

• Trivial tasks: skip this workflow entirely.
• Highly custom business logic: search won't help; note it and implement.
• User says "write it from scratch": respect that, but briefly mention strong existing options.
• Offline: fall back to training knowledge, note you couldn't verify recency.
• Library name confusion (e.g., NextAuth.js -> Auth.js): clarify current name and version.
• Non-technical user: skip the MCP layer (2a) and focus on templates / frameworks.

Domain reference files

Load only the one(s) relevant to the task to keep context lean:

• references/dev.md - Dev tasks: context detection, web search patterns, key resource lists (npm trends, PyPI stats, free-for.dev, GitHub Discussions).
• references/writing.md - Writing and content: Notion, Canva, Google Workspace templates, document frameworks.
• references/data.md - Data, analysis, and ML: Kaggle, Hugging Face, Papers With Code, public datasets.
• references/ops.md - Ops, CI/CD, infra, and process: GitHub Actions, Terraform modules, SOP templates.