🩺

Vector Index Health Check

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

Diagnose a vector index using supplied IDs, source metadata and similarity samples.

Get separate duplicate, orphan and freshness findings with reproducible queries.

Download skill ZIP See the worked example

Free · 2 KB · SKILL.md, instructions and example files. Provide the index schema, source manifest, timestamps and read access or an exported sample.

A worked example

A small example to try before using your own data.

Input

{
  "sources": {
    "doc1": "v2"
  },
  "chunks": [
    {
      "id": "a",
      "source": "doc1",
      "revision": "v1"
    },
    {
      "id": "b",
      "source": "doc2",
      "revision": "v1"
    }
  ]
}

Expected result

{
  "stale_chunks": [
    "a"
  ],
  "orphan_chunks": [
    "b"
  ],
  "duplicate_status": "Not assessed: no embeddings or similarity samples supplied."
}

What to check: Classify a as stale and b as orphan; do not infer duplicates without the necessary data.

Limits: A sample may miss issues. Similarity alone does not prove semantic duplication or justify deletion.

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 = "vector-index-health-check"
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/vector-index-health-check.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() != "29ce2c33704474c1af96c10cf1147588a9a92b231a149de8eb3495ace8144112":
    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/vector-index-health-check/SKILL.md. Codex: ~/.codex/skills/vector-index-health-check/SKILL.md. Keep the complete ZIP folder when helper scripts are included.

🧠 Why it works

Classify a as stale and b as orphan; do not infer duplicates without the necessary data.

⚙️ How it works

Record embedding model/version, chunk identifiers, source IDs and the expected update policy.

Compare index source IDs with the authoritative source manifest to identify definite orphans.

Compare source revision/update markers with index markers to identify stale chunks.

Inspect high-similarity candidates before labeling them duplicates; choose thresholds from the actual embedding/model context.

Return read-only diagnostic steps and a repair proposal; do not delete or re-embed records without authorization.

Description

Get separate duplicate, orphan and freshness findings with reproducible queries.

Provide the index schema, source manifest, timestamps and read access or an exported sample.

Limits: A sample may miss issues. Similarity alone does not prove semantic duplication or justify deletion.