which-tool

Use the Best Tool

Select optimal CLI tools → graceful fallback → research when needed.

<when_to_use>

• Choosing which tool for file search, content search, JSON processing
• Tool taking unexpectedly long for task size
• User expresses frustration with current tool
• Task could be done more elegantly
• Need to verify tool availability before recommending

NOT for: tasks where tool choice is predetermined, simple one-line commands

</when_to_use>

Run detection script before selecting tools:

bun /Users/mg/Developer/outfitter/agents/outfitter/skills/which-tool/scripts/index.ts

Parse output to determine:

• Available modern tools
• Missing tools that could enhance workflow
• System context (OS, package managers)

Cache results per session — no need to re-run unless tool availability changes.

Map task to best available tool:

Task	Preferred	Fallback	Legacy	Notes
Find files by name	fd	-	find	fd: faster, better defaults
Search file contents	rg	-	grep	rg: respects .gitignore, faster
AST-aware code search	sg	rg	grep	sg: structure-aware queries
Process JSON	jq	-	python/node	jq: domain-specific language
View file with syntax	bat	-	cat	bat: syntax highlighting, git diff
List directory	eza	-	ls	eza: modern output, icons
View git diff	delta	-	git diff	delta: side-by-side, syntax highlighting
Navigate directories	zoxide	-	cd	zoxide: frecency-based jumping
Fuzzy select	fzf	-	-	fzf: interactive filtering
HTTP requests	httpie	-	curl	httpie: human-friendly syntax

Selection algorithm:

1. Check detection results for preferred tool
2. If available → use with optimal flags
3. If unavailable → check fallback column
4. If no fallback → use legacy with best-effort flags
5. Note gap if preferred tool would significantly improve workflow

When preferred tool unavailable:

Minor improvement (preferred 10–30% better):

• Use next best option silently
• Don't interrupt workflow

Significant improvement (preferred 2x+ better):

• Use fallback
• Surface suggestion: ◇ Alternative: {TOOL} would be {BENEFIT} — install with {COMMAND}
• Continue without blocking

Critical gap (task extremely tedious with fallback):

• Surface suggestion: ◆ Caution: {TOOL} recommended for this task — {FALLBACK} will be slow/limited
• Offer choice: install now, proceed anyway, defer task

Never block on missing tools — graceful degradation always.

Trigger research when:

• Tool taking 3x+ longer than expected for task size
• User explicitly asks for better approach
• Task seems like it should have specialized tool
• Current tool missing critical feature
• New tool category needed (not in selection table)

Research workflow:

1. Search for {TASK} CLI tool 2025 or {TASK} CLI tool 2024
2. Check GitHub trending in relevant category
3. Evaluate candidates:
   • Speed: benchmarks vs existing tools
   • Ergonomics: default behavior, output format
   • Maintenance: last commit, issue response time
   • Install: complexity, dependencies
   • Compatibility: OS support, integration

Present findings:

• Tool name + one-line description
• Key advantages over current approach
• Installation command
• Usage example for current task
• Trade-offs or caveats

If research yields strong candidate → add to selection table for future reference.

Standard flow:

1. Receive task → categorize task type (find files, search content, process data)
2. Check detection → run script if not yet run this session
3. Select tool → use selection table + detection results
4. Execute → run command with optimal flags
5. Evaluate → if slow/frustrating → trigger research

Research flow:

1. Trigger identified → surface to user with △ This seems slow — research alternatives?
2. User confirms → web search for modern tools
3. Evaluate candidates → speed, ergonomics, maintenance
4. Present findings → tool + advantages + install + example
5. Update knowledge → add to selection table if strong fit

Scenario: Search for authentication code

Task: Find all files containing "authentication" Detection: rg available Selection: Use rg over grep

rg "authentication" --type ts --type js

Scenario: Find config files

Task: Find all YAML files in project Detection: fd available Selection: Use fd over find

fd -e yaml -e yml

Scenario: Process API response

Task: Extract specific fields from JSON Detection: jq unavailable Fallback: Use node/python Suggestion: ◇ Alternative: jq would simplify this — install with brew install jq

node -e "console.log(JSON.parse(require('fs').readFileSync(0, 'utf-8')).field)"

ALWAYS:

• Run detection script before recommending specific tools
• Use selection table to map task to best available tool
• Provide fallback when suggesting tools that might not be installed
• Surface suggestions for significant improvements (2x+ better)
• Trigger research when tool underperforms expectations

NEVER:

• Assume a tool is installed without checking detection results
• Block workflow on missing non-essential tools
• Recommend abandonware or unmaintained tools
• Use legacy tools when modern alternatives are available
• Skip fallback strategy when preferred tool missing

• tool-catalog.md — comprehensive tool documentation
• alternatives.md — how to research new tools
• detection-script.md — detection script implementation