🔄

Query Reformulation Expander

Search & Retrieval · by AIDiveForge · Apr 20, 2026 · Intermediate

Propose retrieval query rewrites and evaluate whether they improve relevant coverage.

Get labeled rewrites, a retrieval comparison and unsupported-claim flags.

Download skill ZIP See the worked example

Free · 2 KB · SKILL.md, instructions and example files. Provide the original query, corpus/index interface and relevance criteria.

A worked example

A small example to try before using your own data.

Input

{
  "query": "How do I resume an agent after a crash?",
  "constraints": [
    "preserve completed tool results"
  ]
}

Expected result

{
  "rewrites": [
    "Agent checkpoint recovery preserving completed tool outputs",
    "Resume interrupted agent execution from persisted state"
  ],
  "hypothetical_passage": "An agent can persist a checkpoint and completed tool identifiers, then recover state without blindly replaying side effects.",
  "status": "Proposed rewrites; retrieval improvement has not been measured."
}

What to check: Preserve the side-effect constraint and label the hypothetical passage as generated, not sourced evidence.

Limits: Rewrites can reduce precision. Without relevance judgments, a larger result set is not proof of improved recall.

Worked example included. Model-specific performance and vendor compatibility have not been benchmarked.

Installation options and other formats

Install this skill

An agent skill starts with SKILL.md. The ZIP also includes its examples and any helper scripts. Drop the file into your tool of choice — or pick a different format if you use Cursor, Windsurf, Copilot, or something else.

Format Download SKILL.md

Quick install — paste into your terminal

python3 - <<'ADF_SKILL_INSTALL'
import hashlib, io, os, stat, tempfile, urllib.request, zipfile
from pathlib import Path, PurePosixPath
folder = "query-reformulation-expander"
root = Path(os.environ.get('ADF_SKILL_ROOT', str(Path.home() / '.claude' / 'skills'))).expanduser()
destination = root / folder
if destination.exists() or destination.is_symlink():
    raise SystemExit('An installation already exists. Back it up and merge the ZIP deliberately.')
root.mkdir(parents=True, exist_ok=True)
request = urllib.request.Request("https://aidiveforge.com/skill/query-reformulation-expander.zip", headers={'User-Agent': 'AIDiveForge-Resource-Installer/1.0 (+https://aidiveforge.com/skills/)'})
with urllib.request.urlopen(request, timeout=30) as response:
    data = response.read(8 * 1024 * 1024 + 1)
if len(data) > 8 * 1024 * 1024 or hashlib.sha256(data).hexdigest() != "e68e7f413b96327fa83867b3427b0cfbd96e71c270f309c2934bbc35f899cf73":
    raise SystemExit('The download did not match this reviewed bundle. No files were installed.')
with zipfile.ZipFile(io.BytesIO(data)) as archive, tempfile.TemporaryDirectory(prefix='.adf-skill-', dir=root) as temporary:
    members = archive.infolist()
    if len(members) > 100 or sum(m.file_size for m in members) > 16 * 1024 * 1024:
        raise SystemExit('Unexpected archive size')
    for member in members:
        name = PurePosixPath(member.filename)
        if name.is_absolute() or '..' in name.parts or not name.parts or name.parts[0] != folder or '\\' in member.filename or stat.S_ISLNK(member.external_attr >> 16):
            raise SystemExit('Unsafe archive entry; nothing was installed')
        target = Path(temporary).joinpath(*name.parts)
        if member.is_dir():
            target.mkdir(parents=True, exist_ok=True)
        else:
            target.parent.mkdir(parents=True, exist_ok=True)
            with target.open('xb') as stream:
                stream.write(archive.read(member))
    staged = Path(temporary) / folder
    if not (staged / 'SKILL.md').is_file() or destination.exists() or destination.is_symlink():
        raise SystemExit('The skill could not be installed without replacing existing data')
    os.rename(staged, destination)
print('Installed the complete skill folder:', destination)
ADF_SKILL_INSTALL

Claude Code: ~/.claude/skills/query-reformulation-expander/SKILL.md. Codex: ~/.codex/skills/query-reformulation-expander/SKILL.md. Keep the complete ZIP folder when helper scripts are included.

🧠 Why it works

Preserve the side-effect constraint and label the hypothetical passage as generated, not sourced evidence.

⚙️ How it works

Extract the user’s actual information need and required constraints before adding terminology.

Produce a few meaning-preserving rewrites plus a clearly labeled hypothetical answer only if the retrieval system supports it.

Run the original and rewrites under the same retrieval settings and preserve result IDs.

Deduplicate results and assess relevance against the original need, not against the hypothetical answer.

Report observed coverage and false positives; claim improved recall only with suitable labeled relevance evidence.

Description

Get labeled rewrites, a retrieval comparison and unsupported-claim flags.

Provide the original query, corpus/index interface and relevance criteria.

Limits: Rewrites can reduce precision. Without relevance judgments, a larger result set is not proof of improved recall.