Smart Exploration

Variant Selection

The prompt optimization system A/B tests explorer prompts to find which wording produces the best exploration results. Before dispatching:

# Select variant for Explorer A
python3 ~/.claude/scripts/prompt-tracker.py select explorer <category> A

# Select variant for Explorer B
python3 ~/.claude/scripts/prompt-tracker.py select explorer <category> B

Each returns {"variant_id": "...", "prompt": "..."}. Use the returned prompt instead of the one in prompt-library.md. Record the variant_id so outcomes can be attributed later.

After Phase 2 completes: Record which files each explorer found. Store this list — it will be compared against files actually used in Phase 5 to compute the exploration quality score.

After Phase 5 completes: Record outcome via:

python3 ~/.claude/scripts/prompt-tracker.py record '{
  "session_id": "<session>",
  "task_category": "<category>",
  "variant_id": "<variant_id>",
  "explorer_role": "<A or B>",
  "files_found": ["file1.py", "file2.py"],
  "files_used_in_impl": ["file1.py", "file3.py", "file4.py"],
  "phase5_retries": 2,
  "plan_steps": 8
}'

Fallback: If prompt-tracker.py is not available or errors, use the prompts from prompt-library.md directly. The optimization system is additive — the workflow works without it.

If 2 prompts are listed for a category, dispatch both in parallel. If only 1 is listed, dispatch it as a single explorer.

Registry-Informed Variant Selection

When the swarm registry exists at .claude/swarm/agent-registry.json, rank prompt variants by findings_used_rate before selecting which to dispatch.

1. Check for registry file. If absent, skip to step 4.
2. For each candidate variant in the target category, look up its variant_id in the registry (variant IDs are tagged in prompt-library.md under each explorer heading).
3. Sort candidates by findings_used_rate descending. Dispatch the top-ranked variant as Explorer A and the second-ranked as Explorer B.
4. Fallback: If the registry file does not exist, has no entries for this category, or errors on read, use the default ordering from prompt-library.md (Explorer A first, Explorer B second).

Registry lookups are read-only during variant selection. Record dispatched events after dispatch using the variant_id returned — this is what feeds the registry data used in future selections.

Task Categories

How to Classify

Use both signals together:

1. The user's request — look for keywords like "add endpoint", "fix bug", "migrate", "refactor", "config", "component", "API", etc.
2. Files or areas mentioned — routes/controllers suggest endpoint; templates/components suggest ui; models/migrations suggest data; external service calls suggest integration.

When both signals agree, classification is confident. When they conflict or the request is ambiguous, default to general.

Examples:

• "Add a /payments/refund endpoint" → endpoint
• "Fix the broken invoice total calculation" → bugfix
• "Add a refunded_at column to invoices" → data
• "Refactor the auth middleware into a shared utility" → refactor
• "Wire up the Stripe webhook handler" → integration
• "Update the dashboard summary card component" → ui
• "Move the DB connection string to an env var" → config
• "Try out a different approach to caching" → exploration
• "Spike whether we can use WebSockets for this" → exploration
• "Help me understand how this feature works" → general

Placeholder Substitution

Each prompt in the library contains one or more placeholders:

• [FEATURE] — the specific feature or capability being added/changed
• [AREA] — the area of the codebase (e.g., "billing", "dashboard", "auth")
• [TARGET] — the specific function, class, or module being refactored or debugged

Always fill these in from the user's request before dispatching. If the request is vague, use the most specific description available (e.g., "the payments module" rather than "some code").

Prompt Library Reference

See prompt-library.md in this skill directory for the complete set of subagent dispatch prompts organized by category.

Fallback Behavior

If the category is unclear after reviewing both signals, use the general prompts. Do not guess aggressively — a well-scoped general exploration is more useful than a narrowly-scoped exploration aimed at the wrong category.