Selecting Agents

What this skill does

# Selecting Agents

## Overview

Use the right agent for the job. Each agent is optimized for specific scenarios and follows a focused workflow.

**This skill helps you choose** which specialized agent to use based on the task at hand.

**For automatic agent selection:** When executing implementation plans, use the `/cipherpowers:execute` command which applies this skill's logic automatically with hybrid keyword/LLM analysis. Manual selection using this skill is for ad-hoc agent dispatch outside of plan execution.

## Agent Selection Logic

When selecting agents (manually or automatically), you must analyze the **task requirements and context**, not just match keywords naively.

**DO NOT use naive keyword matching:**
- ❌ Task contains "ultrathink" → select ultrathink-debugger
- ❌ Task contains "rust" → select rust-agent
- ❌ Task mentions agent name → select that agent

**DO use semantic understanding:**
- ✅ Analyze what the task is asking for (debugging? implementation? review?)
- ✅ Consider task complexity and characteristics
- ✅ Match agent capabilities to task requirements
- ✅ Ignore mentions of agent names that are not prescriptive

**Examples of INCORRECT selection:**
- Task: "Fix simple bug (don't use ultrathink-debugger, it's overkill)" → ❌ Selecting ultrathink-debugger because "ultrathink" appears
- Task: "Implement feature X in Python (not Rust)" → ❌ Selecting rust-agent because "rust" appears
- Task: "Add tests like the code-review-agent suggested" → ❌ Selecting code-review-agent because it's mentioned

**Examples of CORRECT selection:**
- Task: "Fix simple bug in auth.py" → ✅ general-purpose (simple bug, not complex)
- Task: "Investigate random CI failures with timing issues" → ✅ ultrathink-debugger (complex, timing, environment-specific)
- Task: "Add new endpoint to user service (Rust)" → ✅ rust-agent (Rust implementation work)
- Task: "Don't use ultrathink for this simple validation fix" → ✅ general-purpose (task explicitly says it's simple)

**Selection criteria:**
1. **What is the task type?** (implementation, debugging, review, documentation)
2. **What is the complexity?** (simple fix vs multi-component investigation)
3. **What technology?** (Rust code vs other languages)
4. **What is explicitly requested?** (user prescribing specific agent vs mentioning in passing)

**Red flags that indicate you're selecting incorrectly:**
- Selected agent based on keyword appearance alone
- Ignored explicit guidance in task description (e.g., "don't use X")
- Selected debugging agent for simple implementation task
- Selected specialized agent when general-purpose is more appropriate

## Documentation Agents

### technical-writer
**When to use:** After code changes that affect documentation

**Scenarios:**
- Updated API endpoints, added new features
- Changed configuration options or environment variables
- Modified architecture or system design
- Refactored code that impacts user-facing docs
- Added new commands, tools, or workflows

**Skill used:** `maintaining-docs-after-changes`

**Command:** `/cipherpowers:verify docs`

**Key characteristic:** Reactive to code changes - syncs docs with current code state

## Debugging Agents

### ultrathink-debugger
**When to use:** Complex, multi-layered debugging requiring deep investigation

**Scenarios:**
- Production failures with complex symptoms
- Environment-specific issues (works locally, fails in production/CI/Azure)
- Multi-component system failures (API → service → database)
- Integration problems (external APIs, third-party services)
- Timing and concurrency issues (race conditions, intermittent failures)
- Mysterious behavior resisting standard debugging

**Skills used:** `systematic-debugging`, `root-cause-tracing`, `defense-in-depth`, `verification-before-completion`

**Key characteristic:** Opus-level investigation for complex scenarios, not simple bugs

## Development Agents

### rust-exec-agent (for /execute)
**When to use:** Rust tasks during plan execution via `/cipherpowers:execute`

**Scenarios:**
- Executing plan tasks that involve Rust code
- Literal plan following without creative problem-solving
- When blocked behavior is preferred over workarounds

**Key characteristic:** Minimal context (147 words), follows plans literally, reports BLOCKED when stuck

### rust-agent (for ad-hoc work)
**When to use:** Rust development outside of plan execution

**Scenarios:**
- Ad-hoc Rust development (not part of a plan)
- When full TDD and code review workflow is needed
- Exploratory Rust work requiring judgment

**Skills used:** `test-driven-development`, `testing-anti-patterns`, `code-review-reception`

**Key characteristic:** Full workflow with TDD, code review, extensive guidance (~5000+ words with @ expansion)

### code-exec-agent (for /execute)
**When to use:** Non-Rust tasks during plan execution via `/cipherpowers:execute`

**Scenarios:**
- Executing plan tasks that involve non-Rust code
- Literal plan following without creative problem-solving
- When blocked behavior is preferred over workarounds

**Key characteristic:** Minimal context (~150 words), follows plans literally, reports BLOCKED when stuck

### code-agent (for ad-hoc work)
**When to use:** Development outside of plan execution

**Scenarios:**
- Ad-hoc development (not part of a plan)
- When full TDD and code review workflow is needed
- Exploratory work requiring judgment

**Skills used:** `test-driven-development`, `testing-anti-patterns`, `code-review-reception`

**Key characteristic:** Full workflow with TDD, code review, extensive guidance (~5000+ words with @ expansion)

## Review Agents

### code-review-agent
**When to use:** Reviewing code changes before merging

**Scenarios:**
- Before completing feature implementation
- After addressing initial feedback
- When ready to merge to main branch

**Skill used:** `conducting-code-review`

**Command:** `/cipherpowers:code-review`

**Key characteristic:** Structured review process with severity levels (BLOCKING/NON-BLOCKING)

### plan-review-agent
**When to use:** Evaluating implementation plans before execution

**Scenarios:**
- After writing a plan with `/cipherpowers:plan`
- Before executing a plan with `/cipherpowers:execute`
- When plan quality needs validation
- When plan scope or approach is uncertain

**Skill used:** `verifying-plans`

**Command:** `/cipherpowers:verify plan`

**Key characteristic:** Evaluates plan against 35 quality criteria across 6 categories (Security, Testing, Architecture, Error Handling, Code Quality, Process)

## Common Confusions

| Confusion | Correct Choice | Why |
|-----------|----------------|-----|
| "Just finished feature, need docs" | **technical-writer + /summarise** | technical-writer syncs API/feature docs, /summarise captures learning |
| "Quick docs update" | **technical-writer** | All doc maintenance uses systematic process |
| "Fixed bug, should document" | **/summarise command** | Capturing what you learned, not updating technical docs |
| "Changed README" | **Depends** | Updated feature docs = technical-writer. Captured work summary = /summarise |
| "Production debugging done" | **/summarise command** | Document the investigation insights and lessons learned |

## Selection Examples

**Scenario 1: Added new API endpoint**
→ **technical-writer** - Code changed, docs need sync

**Scenario 2: Spent 3 hours debugging Azure timeout**
→ **/summarise command** - Capture the investigation, decisions, solution

**Scenario 3: Both apply - finished user authentication feature**
→ **technical-writer first** - Update API docs, configuration guide
→ **/summarise second** - Capture why you chose OAuth2, what issues you hit

**Scenario 4: Random test failures in CI**
→ **ultrathink-debugger** - Complex timing/environment issue needs deep investigation

**Scenario 5: Simple bug fix in Rust**
→ **rust-agent** - Standard development workflow with TDD

**Scenario 6: Just finished writing implementation plan**
→ **plan-review-agent** - Validate pla