# Jev Shortlist

> Narrow a long list of candidate files down to the ones worth opening, before reading any of them. Use right after a search (grep, rg, find, glob, ls -R, or a Grep/Glob tool call) returns more than ~20 paths and you are about to decide what to read. Scores every candidate in one batched Jev call (sub-second, well under a cent) and returns them ranked, plus a set that is measurably safe to skip. Do NOT use for fewer than ~10 candidates, or to decide whether to edit a file you have already read.

- Skill: `wanlanglin/jev-shortlist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add wanlanglin/jev-shortlist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wanlanglin/jev-shortlist/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: WanLanglin (https://skillmd.com/u/wanlanglin)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/wanlanglin/jev-shortlist

---


# jev-shortlist

A search just handed you 40, or 300, candidate paths. Reading them all burns
context; spawning a search subagent costs seconds and tens of thousands of
tokens. This scores all of them at once and tells you where to start.

## It also runs by itself

Invoking this skill registers a `PostToolUse` hook for `Grep` and `Glob` that
reorders their results for the rest of the session, before you see them. You do
not have to call anything.

The hook **fails open on everything** -- no key, no network, an odd payload,
fewer than 12 results -- and passes the original output through untouched. It
also never deletes: low-scoring results are moved to the bottom under a heading,
not dropped. A search filter that silently loses the one file you needed is
worse than no filter at all.

Run the command below directly when you want to rank something the hook does not
see, such as `find` output or a list you built yourself.

## Use it

Pipe the search output straight in. Plain paths and `path:line:match` both work.

```bash
rg -l "session" src/ | python3 "$CLAUDE_SKILL_DIR/../../scripts/shortlist.py" \
  --task "fix the session fixation vulnerability on login"
```

```bash
# already have a file of paths
python3 .../shortlist.py --task "..." --files candidates.txt --top 10
```

```bash
# machine-readable
python3 .../shortlist.py --task "..." --json < candidates.txt
```

`--task` matters. Give it the actual goal in one sentence, not a keyword. The
measured signal comes almost entirely from the path plus this sentence.

## Reading the output

Two sections. **Read these, highest first** is your queue — work down it and
stop once you have what you need. **Safe to skip** is the conservative part:
in measurement, only about 0–1% of the files an agent genuinely needed ever
landed in that bucket.

Treat this as a **prioritiser, not a filter**. Ranking is good enough to reorder
your reading; it is not good enough to throw away the tail. Recall@10 measured
0.69–0.83, so if you skim only the top 10 you will miss real files. If the task
is safety-critical or you have already been surprised once, read everything and
just use the order.

## Flags worth knowing

- `--skip-threshold` (default `0.10`) — raising it skips more and loses more.
  At 0.2 you skip about half the candidates but lose ~19% of the ones you needed.
  The default is the only value with measured near-zero loss.
- `--context` sends each grep match line too. It costs 3x the tokens and, in a
  same-set A/B, did not reliably improve ranking. Off by default for a reason.
- `--top N` truncates the read queue.

## Cost and latency

One call covers up to 256 candidates. Jev bills the shared content once no
matter how many questions ride along, so a 256-candidate batch measured 11.6k
input tokens, 0.72s, about $0.0005. Under 10 candidates the script skips the
call entirely and just echoes them back.

## Setup

```bash
export TYPESAFE_API_KEY=...   # from typesafe.ai
```

See `references/calibration.md` for how the threshold was derived, on what data,
and what it costs in recall — including the numbers that argue against using
this aggressively.