rewriting

Enhances vague queries for better retrieval with context-aware improvements. Use during adaptive retry when no relevant documents found, when queries are unclear, or when the user mentions query enhancement or rewriting.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill optimizes search retrieval by transforming vague or underspecified user prompts into high-precision queries. By leveraging context-aware rewriting and adaptive retry logic, it ensures AI agents find relevant information even when initial searches fail, significantly improving the reliability and accuracy of RAG (Retrieval-Augmented Generation) systems.

Use Cases

  • Adaptive Search Retry: Automatically reformulating queries when initial document retrieval returns zero results to successfully find relevant content on the second attempt.
  • Contextual Query Expansion: Incorporating previous conversation history into short, follow-up questions (e.g., 'What about the warranty?') to create specific, searchable terms that include the product name.
  • Vague Term Clarification: Converting broad user complaints like 'it won't work' into detailed troubleshooting search strings based on the specific device or software context being discussed.
  • Synonym and Abbreviation Mapping: Expanding technical jargon or abbreviations into descriptive phrases to improve matching performance across diverse knowledge bases.
namerewriting
descriptionEnhances vague queries for better retrieval with context-aware improvements. Use during adaptive retry when no relevant documents found, when queries are unclear, or when the user mentions query enhancement or rewriting.

Query Rewriting

Instructions

Rewrite queries using rewrite_query() in components/rewriter.py. Typically triggered when len(relevant_docs) == 0 during adaptive retry.

Default usage:

# During retry after no relevant docs found
previous_context = f"Previous query '{current_query}' found {len(docs)} documents but none were relevant."

rewrite_result = rewrite_query(current_query, previous_context=previous_context)
current_query = rewrite_result['rewritten_query']

Rewriting strategies:

  • Expand abbreviations: "fast computer" → "high performance laptop processor"
  • Clarify vague terms: "won't work" → "troubleshooting device not powering on"
  • Incorporate context: "What about warranty" + product context → "warranty coverage for [product]"
  • Add synonyms: "cheap" → "affordable budget inexpensive"

Returns:

  • rewritten_query: Enhanced query string
  • reasoning: Explanation of changes

Critical for adaptive retry: Call only when len(relevant_docs) == 0 and num_retries < RETRY_LIMIT. Pass context from previous failed attempt.

Implementation: components/rewriter.py, uses REWRITE_MODEL from config.py (default: Haiku 4.5), temperature 0.3.

Examples

Example 1: Basic rewriting (no context)

# Input
result = rewrite_query("fast computer")

# Output
{
    "rewritten_query": "high performance laptop with fast processor and SSD storage",
    "reasoning": "Expanded 'fast' to specific performance characteristics"
}

Example 2: Context-aware rewriting

# Input
result = rewrite_query(
    "What about warranty",
    previous_context="User interested in ZenithBook 13 Evo laptop"
)

# Output
{
    "rewritten_query": "What is the warranty coverage and terms for ZenithBook 13 Evo laptop",
    "reasoning": "Incorporated product context and made question explicit"
}

Example 3: Adaptive retry integration

# After grading finds no relevant docs
if len(relevant_documents) == 0 and num_retries < RETRY_LIMIT:
    # Build context
    previous_context = f"Previous query '{current_query}' found {len(retrieved_documents)} documents but none were relevant."

    # Rewrite
    rewrite_result = rewrite_query(current_query, previous_context)
    current_query = rewrite_result['rewritten_query']

    print(f"Retry {num_retries + 1}: {current_query}")
    num_retries += 1
    # Loop back to retrieval

Example 4: Vague troubleshooting

# Input
result = rewrite_query("won't work")

# Output
{
    "rewritten_query": "troubleshooting device not functioning properly or not turning on",
    "reasoning": "Clarified vague complaint into specific troubleshooting query"
}