hex-docs-search

What this skill does

# Hex Documentation Search

Comprehensive search for Elixir and Erlang package documentation, following a cascading strategy to find the most relevant and context-aware information.

## When to use this skill

Use this skill when you need to:
- Look up documentation for a Hex package or dependency
- Find function signatures, module documentation, or type specs
- See usage examples of a library or module
- Understand how a dependency is used in the current project
- Search for Elixir/Erlang standard library documentation

## Search strategy

This skill implements a **cascading search** that prioritizes local and contextual information:

1. **Local dependencies** - Search installed packages in `deps/` directory (both source code AND generated docs)
2. **Fetched cache** - Check previously fetched documentation and source code in `.hex-docs/` and `.hex-packages/`
3. **Progressive fetch** - Automatically fetch missing documentation or source code locally when needed
4. **Codebase usage** - Find how packages are used in the current project
5. **HexDocs API** - Search official documentation on hexdocs.pm (fallback)
6. **Web search** - Fallback to general web search (last resort)

## Instructions

### Step 1: Identify the search target

Extract the package name and optionally the module or function name from the user's question.

Examples:
- "How do I use Phoenix.LiveView?" → Package: `phoenix_live_view`, Module: `Phoenix.LiveView`
- "Show me Ecto query examples" → Package: `ecto`, Module: `Ecto.Query`
- "What does Jason.decode!/1 do?" → Package: `jason`, Module: `Jason`, Function: `decode!`

### Step 2: Search local dependencies

Use the **Glob** and **Grep** tools to search the `deps/` directory for BOTH code and documentation:

1. **Find the package directory**:
   ```
   Use Glob: pattern="deps/<package_name>/**/*.ex"
   ```

   If no results, the package isn't installed locally. Skip to Step 4.

2. **Search for module definition in source code**:
   ```
   Use Grep: pattern="defmodule <ModuleName>", path="deps/<package_name>/lib"
   ```

3. **Search for function definition in source code** (if looking for specific function):
   ```
   Use Grep: pattern="def <function_name>", path="deps/<package_name>/lib", output_mode="content", -A=5
   ```

4. **Find documentation in source code** (@moduledoc/@doc annotations):
   ```
   Use Grep: pattern="@moduledoc|@doc", path="deps/<package_name>/lib", output_mode="content", -A=10
   ```

5. **Check for generated HTML documentation** (if available):
   ```
   Use Glob: pattern="deps/<package_name>/doc/**/*.html"
   ```

   If HTML docs exist, search them for relevant content:
   ```
   Use Grep: pattern="<ModuleName>|<function_name>", path="deps/<package_name>/doc"
   ```

6. **Read the relevant files** using the Read tool to get full context from either source or HTML docs.

### Step 3: Check fetched cache and fetch if needed

If the package wasn't found in `deps/`, check for previously fetched documentation or source code, or fetch it now.

#### 3.1: Check fetched documentation cache

Use the **Glob** tool to check if documentation was previously fetched:

```
Use Glob: pattern=".hex-docs/docs/hexpm/<package_name>/*/*.html"
```

If found, search the fetched documentation using the same patterns as Step 2 (sections 5 and 6).

#### 3.2: Check fetched source code cache

Use the **Glob** tool to check if source code was previously fetched:

```
Use Glob: pattern=".hex-packages/<package_name>-*/**/*.ex"
```

If found, search the fetched source using the same patterns as Step 2 (sections 2-4).

#### 3.3: Determine version to fetch

If no cached docs or source found, determine which version to fetch:

1. **Check mix.lock** for locked version:
   ```
   Use Bash: grep '"<package_name>"' mix.lock | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
   ```

2. **Check mix.exs** for version constraint:
   ```
   Use Bash: grep -E '\{:<package_name>' mix.exs | grep -oE '[0-9]+\.[0-9]+\.[0-9]+'
   ```

3. **Get latest version from hex.pm**:
   ```
   Use Bash: curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version'
   ```

4. **If version ambiguous**, use **AskUserQuestion** to prompt:
   ```
   Question: "Package '<package_name>' not found locally. Which version would you like to fetch?"
   Options:
   - "Latest (X.Y.Z)" - Fetch most recent release
   - "Project version (X.Y.Z)" - Use version from mix.exs/mix.lock (if available)
   - "Specific version" - User provides custom version in "Other" field
   - "Skip fetching" - Continue to HexDocs API search without fetching
   ```

#### 3.4: Progressive fetch (documentation first)

Once version is determined, fetch documentation to project-local cache:

```bash
# Use custom HEX_HOME to store in project directory
HEX_HOME=.hex-docs mix hex.docs fetch <package_name> <version>
```

**Storage location**: `.hex-docs/docs/hexpm/<package_name>/<version>/`

If successful:
- Search the fetched HTML documentation using patterns from Step 2 (sections 5-6)
- Read relevant files with the Read tool

If **documentation fetch fails** (package has no docs) or **docs lack sufficient detail**:
- Proceed to Step 3.5 to fetch source code

#### 3.5: Fetch source code if needed

If documentation is insufficient or unavailable, fetch package source code:

```bash
# Fetch and unpack to project-local directory
mix hex.package fetch <package_name> <version> --unpack --output .hex-packages/<package_name>-<version>
```

**Storage location**: `.hex-packages/<package_name>-<version>/`

If successful:
- Search the source code using patterns from Step 2 (sections 2-4)
- Read source files with the Read tool
- Examine @moduledoc and @doc annotations

If **source fetch fails**:
- Continue to Step 5 (HexDocs API search) as fallback

#### 3.6: Git ignore recommendation

Inform the user that fetched content should be git-ignored. Suggest adding to `.gitignore`:

```gitignore
# Fetched Hex documentation and packages
/.hex-docs/
/.hex-packages/
```

This only needs to be mentioned once per session, and only if fetching actually occurred.

### Step 4: Search codebase usage

Use the **Grep** tool to find usage patterns in the current project:

1. **Find imports and aliases**:
   ```
   Use Grep: pattern="alias <ModuleName>|import <ModuleName>", path="lib", output_mode="content", -n=true
   ```

2. **Find function calls**:
   ```
   Use Grep: pattern="<ModuleName>\.", path="lib", output_mode="content", -A=3
   ```

3. **Search test files for examples**:
   ```
   Use Grep: pattern="<ModuleName>", path="test", output_mode="content", -A=5
   ```

This provides **real-world usage examples** from the current project, which is often the most helpful context.

### Step 5: Search HexDocs Search API

If local search doesn't provide sufficient information, use the **Bash** tool to search the HexDocs search API.

**Full-text search across documentation:**

```bash
# Search across all packages
curl -s "https://search.hexdocs.pm/?q=<query>&query_by=doc,title" | jq -r '.found, .hits[0:5][] | .document | "\(.package) - \(.title)\n\(.doc)\n---"'

# Search within a specific package (get version first)
VERSION=$(curl -s "https://hex.pm/api/packages/<package_name>" | jq -r '.releases[0].version')
curl -s "https://search.hexdocs.pm/?q=<query>&query_by=doc,title&filter_by=package:=[<package>-$VERSION]" | jq -r '.hits[] | .document | "\(.title)\n\(.doc)\nURL: https://hexdocs.pm\(.url)\n---"'
```

**Examples:**

```bash
# Search for "mount" in phoenix_live_view
VERSION=$(curl -s "https://hex.pm/api/packages/phoenix_live_view" | jq -r '.releases[0].version')
curl -s "https://search.hexdocs.pm/?q=mount&query_by=doc,title&filter_by=package:=[phoenix_live_view-$VERSION]" | jq -r '.hits[0:3][] | .document | "\(.title)\n\(.doc)\n---"'

# General search for Ecto.Query
curl -s "https://search.hexdocs.pm/?q=Ecto.Query&query_by=doc,title" | jq -r '.hits[0:5][] | .document | "\(.package) - \(.title)\n\(.doc)\n"'
```

**API Response structure: