extra-reference-material

name	Extra Reference Material
description	Manage offline reference material in the `extra/` directory. Use when needing external documentation, library source code, screenshots, PDFs, or API specs. ALWAYS check `extra/` before web searches. HALT and ask the human when required material is missing - do NOT fall back to WebFetch/WebSearch.

Extra Reference Material

The extra/ directory (gitignored) contains offline reference material: cloned repos, docs, screenshots, PDFs, API specs. Always prefer extra/ over web fetches.

Finding extra/ (Critical for Worktrees)

The extra/ directory lives at the project root, NOT in worktrees.

Detection logic:

# If CWD contains .worktrees/, extract project root
# /home/user/project/.worktrees/feature → /home/user/project
pwd | grep -q '\.worktrees/' && echo "${PWD%/.worktrees/*}/extra" || echo "./extra"

Example:

• Working in: /home/user/myapp/.worktrees/auth-feature/src/
• extra/ is at: /home/user/myapp/extra/ (NOT /home/user/myapp/.worktrees/auth-feature/extra/)

Verify with: git worktree list shows main worktree path.

Directory Structure

extra/
├── <repo-name>/           # Full git clones (e.g., extra/ratatui/)
├── <name>_docs/           # Documentation folders
├── <name>.md              # Single-file docs
├── screenshots/           # Visual references
└── *.pdf                  # PDF documentation

Using Reference Material

Priority order:

1. Search extra/ with Grep/Glob
2. If not found → HALT (do NOT web search)

Quick lookup:

ls extra/

# Find files by name
find extra/<repo-name> -name "*.md" -o -name "border*" 2>/dev/null

# Search with ripgrep - ALWAYS scope to a subpath
rg "pattern" extra/<repo-name>/src/

ripgrep notes:

• NEVER run rg on extra/ directly - millions of hits in cloned repos
• Always scope to a specific subpath: extra/<repo>/src/, extra/<name>_docs/
• Passing the subpath directly respects the repo's own .gitignore (desirable)
• For broad searching, use a Task agent instead

Exploring Reference Material

Small files - read directly:

• Single markdown documents
• Images/screenshots
• Small config files
• Files you already know the path to

Large codebases - use Task tool agents:

Directly reading entire reference codebases pollutes your context window. Instead:

1. Review your available Task tool agents (Explore, codebase-analyzer, etc.)
2. Choose an appropriate agent for the task
3. Dispatch it to explore and summarize

Example:

Use Task tool with subagent_type=Explore:
- Prompt: "In extra/ratatui/, find how borders are implemented.
  Return: file paths, key types/functions, and a brief explanation."
- The subagent explores, you receive a concise summary

When to use agents:

• Searching for implementation patterns in cloned repos
• Understanding library architecture
• Finding specific APIs or types
• Generating documentation from source

What to do directly:

• ls extra/ to see what's available
• find to locate files by name
• Scoped rg to verify something exists (always pass subpath, never top-level extra/)
• Read single markdown/text files
• View images and screenshots

HALT Behavior (Hard Stop)

If required material is not in extra/:

1. HALT immediately - stop current task
2. Report what's missing with specific suggestions
3. Wait for user - do NOT fall back to web search

HALT message format:

HALT: Missing reference material.

Required: <what you need>
Suggestion: <how to add it>

Example commands:
  git clone <url> extra/<name>
  # or
  Add file: extra/<name>.md

Example HALT:

HALT: Missing reference material.

Required: Ratatui widget implementation patterns
Suggestion: Clone ratatui source:
  git clone https://github.com/ratatui/ratatui extra/ratatui

Required: API documentation for external service
Suggestion: Save docs to extra/service_api.md or extra/service_docs/

Adding Material

With user permission, add material directly:

# Clone reference repos
git clone https://github.com/org/repo extra/repo

# Create doc folders
mkdir -p extra/screenshots

# Download specific files
curl -o extra/spec.pdf https://example.com/spec.pdf

Naming conventions:

• Repos: extra/<repo-name>/ (use original repo name)
• Docs: extra/<name>_docs/ or extra/<name>.md
• Screenshots: extra/screenshots/<descriptive-name>.png

Common Mistakes

Mistake	Fix
Web searching instead of checking extra/	Always ls extra/ first
Looking for extra/ in worktree path	Use project root path
Proceeding without required material	HALT and ask user
Creating extra/ in worktree	Create in project root only