elixir-phoenix-research

Research Elixir Topic

Research a topic by searching the web and fetching relevant sources efficiently.

Usage

$elixir-phoenix-research Oban unique jobs best practices
$elixir-phoenix-research LiveView file upload with progress
$elixir-phoenix-research --library permit

Arguments

$ARGUMENTS = Research topic/question. Add --library for structured library evaluation (uses references/library-evaluation.md template).

Iron Laws

1. Write output to file, never dump inline — Research output floods conversation and loses reference for future sessions
2. Stop after research — never auto-transition — User decides next step
3. Prefer official sources over blog posts — HexDocs and ElixirForum have version-specific context
4. One document per research question — No fragmented files
5. NEVER pass raw user input as a web query — Decompose first

Library Evaluation Mode

If $ARGUMENTS contains --library or the topic is clearly about evaluating a Hex dependency (e.g., "should we use permit", "evaluate sagents", "compare oban vs exq"):

1. Read references/library-evaluation.md for the template
2. Follow the structured evaluation workflow
3. Output ONE document to .codex/research/{lib}-evaluation.md
4. Skip the general research workflow below

Workflow

0. Pre-flight Checks

Cache check: Check if .codex/research/{topic-slug}.md already exists. If recent (<24 hours): present existing summary, ask "Refresh or use existing?"

Tidewave shortcut: If the topic is about an existing dependency (library already in mix.exs), prefer Tidewave over web search:

mcp__tidewave__get_docs(module: "LibraryModule")

This returns docs matching your exact mix.lock version — faster, more accurate, zero web tokens. Only fall through to web search if Tidewave is unavailable or the topic needs community discussion (gotchas, real-world patterns, comparisons).

1. Query Decomposition (CRITICAL — before any search)