Imported from stevenjmiklovic/solrcompass (skills/search-strategist/SKILL.md). Install upstream with npx skills add stevenjmiklovic/solrcompass --skill search-strategist. Copyright stays with the author (Apache-2.0).

Search Strategist

Specialized skill for finding the most relevant content across all indexed collections using optimized, multi-pass search strategies.

Overview

This skill transforms user questions into effective search operations by:

1. Classifying the question type and intent
2. Planning a search strategy (scope, mode, filters, chaining)
3. Executing the search with appropriate parameters
4. Evaluating result quality and iterating if needed
5. Synthesizing findings from multiple sources into a coherent answer

When to Activate

Use this skill when:

• A user asks a question that indexed content could answer
• Search results are poor and need optimization
• Multiple collections might contain complementary information
• The user needs to discover something without knowing where it lives
• A complex question requires decomposition into sub-queries

Question Classification

Classify the user's question to determine the best search approach:

Strategy Planning

Decision Matrix: Scope Selection

What is the user looking for?
├── Source code → compass_search_codebase
│   ├── Specific repo? → add root filter
│   └── All repos? → omit root
├── Project conventions / past decisions → compass_recall_memory
├── Knowledge artifacts / best practices → compass_search (scope: artifacts)
├── User documents → compass_search (scope: documents)
├── Could be anywhere → compass_search (scope: all)
└── Task-relevant guidance → compass_recall

Decision Matrix: Mode Selection

What does the query look like?
├── Exact identifier (function name, class, variable) → keyword
├── Natural language question → hybrid
├── Abstract concept (no specific terms expected) → vector
├── Mixed (some terms + some concepts) → hybrid
└── Unsure → hybrid (best default)

Parameter Tuning

Multi-Pass Strategies

Strategy 1: Funnel (Broad → Narrow)

For exploratory questions where the answer location is unknown:

1. Broad pass — Low minScore, high topK, wide scope:

   compass_search {
     "query": "<natural language question>",
     "scope": "all",
     "mode": "hybrid",
     "topK": 10,
     "minScore": 0.4
   }

2. Analyze results — Identify which collection/scope has the best hits
3. Narrow pass — Targeted scope, refined query using terms from results:

   compass_search_codebase {
     "query": "<refined query using discovered terminology>",
     "root": "<identified repo>",
     "mode": "hybrid",
     "topK": 5,
     "minScore": 0.6
   }

Strategy 2: Parallel (Multiple Scopes Simultaneously)

For questions that span code and documentation:

1. Code pass:

   compass_search_codebase {
     "query": "<implementation-focused query>",
     "mode": "hybrid",
     "topK": 5
   }

2. Knowledge pass:

   compass_search {
     "query": "<conceptual query>",
     "scope": "artifacts",
     "mode": "hybrid",
     "topK": 5
   }

3. Memory pass:

   compass_recall_memory {
     "query": "<convention/decision query>",
     "topK": 3
   }

4. Synthesize — Combine findings, noting where code diverges from guidance

Strategy 3: Chain (Result-Guided)

When the first search reveals what to look for next:

1. Initial search to identify relevant artifacts or files
2. Use result metadata (artifact names, file paths, tags) to refine the next query
3. Load full content for the most relevant hits
4. Pass used names to exclude to avoid repetition:

   compass_recall {
     "context": "<updated context from initial results>",
     "topK": 3,
     "exclude": ["already-seen-artifact"]
   }

Strategy 4: Decompose (Complex Questions)

For multi-part questions, break into sub-queries:

Example: "How does authentication work and where is it configured?"

1. Sub-query 1: "authentication implementation middleware" → codebase
2. Sub-query 2: "authentication configuration settings" → codebase
3. Sub-query 3: "authentication architecture decisions" → memory + artifacts
4. Merge results into a structured answer covering implementation, config, and rationale

Query Optimization

When Results Are Poor

If the initial search returns irrelevant or no results, apply these fixes in order:

1. Lower minScore — Results may exist but below the threshold
2. Switch mode — Try vector if keyword failed, or vice versa
3. Rephrase — Use synonyms or different abstraction level:
   • Too abstract: "data persistence" → "database write operation"
   • Too specific: "handleUserAuthCallback" → "authentication callback handler"
4. Broaden scope — Switch from artifacts to all, or remove root filter
5. Increase topK — Relevant results may be ranked lower
6. Check indexed content — Run compass_status to confirm content exists

Query Reformulation Techniques

Mode-Specific Tips

Keyword mode works best with:

• Function/class/variable names
• File paths or module names
• Error messages or log patterns
• Configuration keys

Vector mode works best with:

• Natural language descriptions of behavior
• Concepts without specific terminology
• "What does X do?" style questions
• Cross-language concept matching

Hybrid mode works best with:

• Mixed queries (some keywords + some concepts)
• Most general-purpose questions
• When unsure which mode to use

Result Evaluation

After each search, assess quality:

Answer Synthesis

After gathering results from one or more searches:

1. Rank by relevance to the original question (not just search score)
2. Note the source — distinguish code (how it IS) from artifacts (how it SHOULD be) from memory (what was DECIDED)
3. Highlight conflicts — if code diverges from documented guidance, flag it
4. Cite locations — provide file paths, artifact names, or memory tags
5. Identify gaps — note if the question is only partially answered and suggest what to index next

Integration with Other Skills

• Before indexing (codebase-indexer): Use this skill to test what's searchable vs. missing
• After memory storage (memory-curator): Verify the note is recallable with expected queries
• With workspace profiling: Use profile results to inform which artifacts to search first