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:

• Check detection results for preferred tool

• If available → use with optimal flags

• If unavailable → check fallback column

• If no fallback → use legacy with best-effort flags

• 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:

• Search for {TASK} CLI tool 2025 or {TASK} CLI tool 2024

• Check GitHub trending in relevant category

• 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:

• Receive task → categorize task type (find files, search content, process data)

• Check detection → run script if not yet run this session

• Select tool → use selection table + detection results

• Execute → run command with optimal flags

• Evaluate → if slow/frustrating → trigger research

Research flow:

• Trigger identified → surface to user with △ This seems slow — research alternatives?

• User confirms → web search for modern tools

• Evaluate candidates → speed, ergonomics, maintenance

• Present findings → tool + advantages + install + example

• 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