tool-selection-framework

What this skill does

# Tool Selection Framework

## Purpose

Enable developers to select the right AI tool for each development task through systematic evaluation of context requirements, codebase characteristics, and task complexity. This skill helps:
- Match tool capabilities (context window, reasoning depth, cost) to task requirements
- Design multi-phase workflows that leverage tool-specific strengths
- Optimize context utilization by choosing appropriate tool for codebase size
- Balance cost, performance, and reasoning depth based on project constraints
- Avoid wasting context with mismatched tool selection
- Create extensible decision frameworks that adapt to new tools

## When to Activate

Use this skill when:
- Starting new project with uncertain tool requirements
- Codebase size approaches/exceeds Claude Code context limits (200K tokens)
- Task requires broad exploration (large codebase analysis, pattern discovery)
- Task requires deep reasoning (architectural decisions, security analysis)
- Multi-phase workflow needed (exploration → implementation)
- Optimizing cost/performance balance for long-term project
- Team asks "Should we use Claude Code or Gemini CLI for this?"
- Students learning context-aware development tool selection

## Persona

"Think like a resource optimization engineer allocating specialized tools to tasks where each tool excels. Your goal is to maximize development productivity by matching tool capabilities—context window size, reasoning depth, cost efficiency—to specific task characteristics such as codebase size, complexity, and phase (exploration vs implementation)."

## Questions (Analysis Framework)

Before selecting a tool or designing a multi-tool workflow, analyze through these questions:

### Question 1: Codebase Size Assessment
**"How many lines of code does this project have?"**

**Size Categories**:
- **< 50K lines** → Claude Code sufficient
  - **Rationale**: 200K context window handles full codebase + conversation
  - **Action**: Use Claude Code exclusively
  - **Example**: Small web app, CLI tool, microservice

- **50K-500K lines** → Evaluate task type
  - **Rationale**: Codebase fits in Gemini (2M context) but may fit Claude Code with selective loading
  - **Decision depends on**: Task type (exploration vs focused), reasoning depth needed
  - **Action**: Apply Task Type Analysis (Question 2)
  - **Example**: Medium web application, API backend, data processing system

- **> 500K lines** → Gemini for exploration, Claude Code for implementation
  - **Rationale**: Full codebase exceeds Claude Code context; Gemini handles broad analysis
  - **Action**: Multi-phase workflow (Gemini → Claude Code)
  - **Example**: Large monolith, multi-service platform, legacy system

**How to measure**:
```bash
# Count lines of code (excluding comments, blank lines)
cloc . --exclude-dir=node_modules,venv
```

### Question 2: Task Type Evaluation
**"Is this an exploration task or focused implementation?"**

**Exploration Tasks** (Broad understanding, pattern discovery):
- Understanding unknown codebase architecture
- Finding all instances of pattern X across system
- Analyzing how feature Y is implemented everywhere
- Discovering dependencies and relationships
- Mapping data flow through large system
- **Tool recommendation**: Gemini CLI (2M context for broad scan)

**Focused Implementation** (Specific feature, bounded scope):
- Implementing one feature in known module
- Fixing specific bug in identified component
- Refactoring isolated function/class
- Adding unit tests for existing code
- Writing documentation for single module
- **Tool recommendation**: Claude Code (200K context sufficient, deep reasoning)

**Hybrid Tasks** (Both exploration and implementation):
- Feature spanning multiple unfamiliar modules
- Refactoring across unknown codebase
- Performance optimization requiring system understanding
- **Tool recommendation**: Multi-phase (Gemini explore → Claude Code implement)

### Question 3: Reasoning Depth Requirements
**"Does this task need deep architectural reasoning or surface-level pattern matching?"**

**Deep Reasoning Tasks** (Architectural decisions, tradeoffs, security):
- System design decisions (choosing architecture)
- Security analysis (finding vulnerabilities)
- Performance optimization (algorithmic improvements)
- Complex refactoring (maintaining correctness)
- Architectural decision records (weighing tradeoffs)
- **Tool recommendation**: Claude Code (superior reasoning, latest models)

**Pattern Matching Tasks** (Applying known solutions, generating boilerplate):
- Generating CRUD operations
- Creating standard API endpoints
- Writing boilerplate configuration
- Finding code duplication
- Applying consistent formatting
- **Tool recommendation**: Either tool (pattern matching doesn't require deepest reasoning)

**Exploration Tasks** (Understanding existing patterns):
- Reading unfamiliar codebase
- Understanding how system works
- Finding where functionality lives
- Mapping component relationships
- **Tool recommendation**: Gemini CLI (2M context for comprehensive scan)

### Question 4: Context Budget Constraints
**"What's the token budget for this task?"**

**Tight Budget** (Cost-sensitive, optimize per-token value):
- Personal projects (low budget)
- Repetitive tasks (frequent tool use)
- Learning/experimentation (many sessions)
- **Tool recommendation**: Claude Code (lower cost per token)
- **Strategy**: Use progressive loading, compress context aggressively

**Liberal Budget** (Exploration prioritized, cost secondary):
- Professional projects (budget allocated)
- One-time migrations (rare event, worth investment)
- Critical understanding needed (business value justifies cost)
- **Tool recommendation**: Gemini CLI acceptable for exploration
- **Strategy**: Load full codebase, comprehensive analysis

**Balanced Budget** (Cost matters, but productivity critical):
- Most development work
- **Tool recommendation**: Match tool to task (don't waste context)
- **Strategy**: Use Claude Code for focused work, Gemini sparingly for exploration

### Question 5: Time Sensitivity
**"Is this task time-critical?"**

**Time-Critical** (Fast iteration needed):
- Production bug fix (downtime costly)
- Urgent feature request (deadline pressure)
- Blocking issue (team waiting)
- **Tool recommendation**: Claude Code (faster response, optimized for development)
- **Strategy**: Focus scope, load only essential context

**Non-Time-Critical** (Thorough understanding prioritized):
- Learning new codebase (onboarding)
- Architectural planning (design phase)
- Technical debt analysis (long-term planning)
- **Tool recommendation**: Gemini CLI acceptable (thorough exploration worth time)
- **Strategy**: Comprehensive analysis, multi-phase if needed

### Question 6: Expertise Level
**"Do you already understand this codebase?"**

**Expert** (Familiar with codebase, know where things are):
- **Tool recommendation**: Claude Code (focused work in known areas)
- **Strategy**: Load relevant files, skip exploration

**Intermediate** (General familiarity, need occasional reference):
- **Tool recommendation**: Claude Code with on-demand loading
- **Strategy**: Foundation context + fetch references as needed

**Novice** (New to codebase, need broad understanding):
- **Tool recommendation**: Gemini CLI for initial exploration
- **Strategy**: Multi-phase (Gemini learn → Claude Code implement)

## Principles

### Principle 1: Right Tool for the Job
**"Don't use Gemini when Claude Code suffices; don't constrain Claude Code when Gemini excels."**

Match tool to task characteristics:
- **Small codebase** (<50K lines) → Claude Code (no need for 2M context)
- **Large codebase** (>500K lines) → Gemini for exploration (2M context handles full codebase)
- **Deep reasoning** (architecture, security) → C