keyword-expansion_skill

Overview

This skill expands and refines search keywords to improve recall and precision for research pipelines while preventing scope drift. It updates queries.md with additions, explicit exclusions, and a short rationale for every change. The goal is more effective, maintainable queries without exploding query count or introducing noise.

How this skill works

The skill inspects queries.md (and optional DECISIONS.md) to extract current topic scope and existing exclusions. It proposes synonyms, acronyms, related terms, and targeted exclusion rules, then merges and structures these into a constrained set of updated queries. Each change in queries.md includes a concise why note explaining the rationale and expected impact.

When to use it

• Recall is low or search returns miss relevant results
• Search returns lots of irrelevant noise or common false positives
• Topic has many aliases, acronyms, or variant spellings to normalize
• You need to systematize query coverage before large-scale retrieval
• queries.md lacks explicit exclusions or clear rationale for terms

Best practices

• Start by extracting explicit scope and constraints from DECISIONS.md if present
• Favor a small set of high-signal queries and merge synonyms into single queries
• Add clear, targeted exclusions for frequent false positives instead of broad terms
• Document a one-line why for each addition or removal to keep changes auditable
• Limit the total query count and prefer consolidated patterns over many near-duplicates

Example use cases

• Expand a seed query to include common acronyms and misspellings while excluding unrelated domains
• Refine queries after observing topical drift in search results by adding exclusion rules
• Normalize multiple synonyms into grouped queries to reduce redundancy before large indexing
• Update queries.md to reflect new terminology introduced during a multi-month research project
• Audit queries.md to ensure changes align with DECISIONS.md and revert drift-causing additions