usage-rules

What this skill does

# Usage Rules Search

Comprehensive search for Elixir and Erlang package usage rules and best practices, following a cascading strategy to find the most relevant coding conventions and patterns.

## When to use this skill

Use this skill when you need to:
- Look up coding conventions for a Hex package
- Find best practices and recommended patterns
- See good/bad code examples for proper usage
- Understand common mistakes to avoid
- Learn package-specific idioms and conventions
- Get context-aware recommendations for implementation

## Search strategy

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

1. **Local dependencies** - Search installed packages in `deps/` directory for usage-rules.md
2. **Fetched cache** - Check previously fetched usage rules in `.usage-rules/`
3. **Progressive fetch** - Automatically fetch package and extract usage-rules.md if missing
4. **Context-aware extraction** - Extract relevant sections based on coding context
5. **Fallback** - Note when package doesn't provide usage rules, suggest alternatives

## Instructions

### Step 1: Identify the package and context

Extract the package name and identify the coding context from the user's question.

**Package name examples**:
- "Ash best practices" → Package: `ash`
- "Phoenix LiveView patterns" → Package: `phoenix_live_view`
- "How to use Ecto properly?" → Package: `ecto`

**Context keywords**:
- Querying: "query", "filter", "search", "find", "list"
- Error handling: "error", "validation", "exception", "handle"
- Actions: "create", "update", "delete", "action", "change"
- Relationships: "relationship", "association", "belongs_to", "has_many"
- Testing: "test", "testing", "mock", "fixture"
- Authorization: "authorization", "permissions", "policy", "access"
- Structure: "structure", "organization", "architecture", "setup"

### Step 2: Search local dependencies

Use the **Glob** and **Grep** tools to search the `deps/` directory for usage rules:

1. **Find the package directory with usage-rules.md**:
   ```
   Use Glob: pattern="deps/<package_name>/usage-rules.md"
   ```

   If no results, the package isn't installed locally or doesn't provide usage rules. Skip to Step 3.

2. **Check for sub-rules** (advanced packages may have specialized rules):
   ```
   Use Glob: pattern="deps/<package_name>/usage-rules/*.md"
   ```

3. **Search for relevant sections** based on context keywords:
   ```
   Use Grep: pattern="^## (Querying|Error Handling|Actions)", path="deps/<package_name>/usage-rules.md", output_mode="content", -n=true
   ```

   This finds section headings with line numbers.

4. **Extract relevant sections**:
   ```
   Use Grep: pattern="^## Error Handling", path="deps/<package_name>/usage-rules.md", output_mode="content", -A=50
   ```

   Use `-A` flag to get section content (adjust number based on typical section length).

5. **Read the complete file** if needed for broader context:
   ```
   Use Read: file_path="deps/<package_name>/usage-rules.md"
   ```

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

If the package wasn't found in `deps/`, check for previously fetched usage rules, or fetch them now.

#### 3.1: Check fetched cache

Use the **Glob** tool to check if usage rules were previously fetched:

```
Use Glob: pattern=".usage-rules/<package_name>-*/usage-rules.md"
```

If found, search the cached rules using the same patterns as Step 2 (sections 3-5).

#### 3.2: Determine version to fetch

If no cached rules 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>' usage rules 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 without usage rules
   ```

#### 3.3: Fetch package and extract usage rules

Once version is determined, fetch the package and extract usage-rules.md:

```bash
# Create temp directory and fetch package
mkdir -p .usage-rules/.tmp
mix hex.package fetch <package_name> <version> --unpack --output .usage-rules/.tmp/<package_name>-<version>

# Check if usage-rules.md exists
if [ -f ".usage-rules/.tmp/<package_name>-<version>/usage-rules.md" ]; then
  # Create version-specific directory
  mkdir -p ".usage-rules/<package_name>-<version>"

  # Copy main usage rules file
  cp ".usage-rules/.tmp/<package_name>-<version>/usage-rules.md" ".usage-rules/<package_name>-<version>/"

  # Copy sub-rules if present
  if [ -d ".usage-rules/.tmp/<package_name>-<version>/usage-rules/" ]; then
    cp -r ".usage-rules/.tmp/<package_name>-<version>/usage-rules/" ".usage-rules/<package_name>-<version>/"
  fi

  echo "Usage rules cached in .usage-rules/<package_name>-<version>/"
else
  echo "Package does not provide usage-rules.md"
fi

# Clean up temp directory
rm -rf ".usage-rules/.tmp/<package_name>-<version>"
```

**Storage location**: `.usage-rules/<package_name>-<version>/`

If successful:
- Search the cached usage rules using patterns from Step 2
- Read relevant files with the Read tool

If **package doesn't include usage-rules.md**:
- Package may not have adopted usage rules convention
- Proceed to Step 5 (fallback suggestions)

#### 3.4: Git ignore recommendation

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

```gitignore
# Fetched usage rules
/.usage-rules/
```

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

### Step 4: Extract relevant sections based on context

Usage rules files can be large (1000+ lines). Extract only relevant sections to avoid context overload.

#### 4.1: Find section headings

```bash
# Find all h2 section headings with line numbers
Use Grep: pattern="^## ", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -n=true
```

This returns a list like:
```
7:## Understanding Ash
13:## Code Structure & Organization
21:## Code Interfaces
85:## Actions
120:## Querying Data
```

#### 4.2: Match context to sections

Based on user's context keywords, identify relevant sections:

**Context: "querying"** → Look for sections containing:
- "Querying", "Query", "Filters", "Search", "Find"

**Context: "error handling"** → Look for sections containing:
- "Error", "Validation", "Exception", "Handle"

**Context: "actions"** → Look for sections containing:
- "Actions", "Create", "Update", "Delete", "CRUD"

#### 4.3: Extract matched sections

```bash
# Extract specific section with content
Use Grep: pattern="^## Querying Data", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -A=80
```

**Adjust `-A` value** based on typical section length:
- Small sections (< 50 lines): `-A=50`
- Medium sections (50-150 lines): `-A=100`
- Large sections (> 150 lines): `-A=150` or read specific ranges

#### 4.4: Include code examples

Look for code blocks within sections:

```bash
# Find code examples in section
Use Grep: pattern="```elixir|# GOOD|# BAD", path=".usage-rules/<package>-<version>/usage-rules.md", output_mode="content", -A=10
```

Code examples often include:
- **Good patterns**: Marked with `# GOOD`, `# PREFERRED`
- **Bad patterns**: Marked with `# BAD`, `# AVOID`, `# WRONG`
- **Inline comments**: Explanatory comments in code blocks

### Step 5: Present usage rules

Format the output based on