bib-search-citation

What this skill does

# Bib Search Citation

## Capability Summary

Use this skill when the user provides a local `.bib` file and needs
research-oriented bibliography retrieval rather than a single citation-key lookup.
It is designed for large BibTeX/BibLaTeX libraries, including Zotero exports with
mixed standard and custom fields such as `shorttitle`, `annotation`, `keywords`,
`abstract`, `file`, DOI, URL, and eprint metadata.

The skill can:

- search by topic words and field-specific filters
- filter by author, year, entry type, DOI, arXiv/eprint, PDF, code, keywords,
  annotation, or abstract
- return stable JSON for downstream tooling
- generate compact human-readable previews from JSON results
- emit LaTeX and Typst citation snippets
- return raw BibTeX only when exact export or manual verification requires it

## Triggering

Use this skill for requests such as:

- "Search my `.bib` file for recent Mamba forecasting papers."
- "Find entries by Cheng after 2024 that have code and return cite snippets."
- "Show the raw BibTeX for the best TimeMachine match."
- "Filter Zotero-exported entries whose annotation mentions CodeAvailable."
- "Preview the JSON output from a saved bibliography search."

If the user gives only a natural-language request, infer a conservative search
spec and state the assumptions. If the user gives a compact filter expression,
preserve it as closely as possible instead of translating it into vague prose.

## Do Not Use

Do not use this skill for:

- validating citations already used inside a `.tex` or `.typ` project
- compiling, formatting, or diagnosing manuscript source trees
- rewriting related-work prose
- online literature discovery when there is no local bibliography file
- inventing missing bibliographic metadata that is not present in the `.bib` file

For manuscript citation integrity, use the relevant writing skill's bibliography
module. For online paper discovery, use a research-oriented workflow and verify
metadata from external sources before adding it to a library.

## Module Router

| Module      | Best for                                                       | Command                                                                                                                                                                 |
| ----------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`     | one-shot compact search with inline filters                    | `uv run python -B $SKILL_DIR/scripts/search_bib.py --bib references.bib --query 'mamba forecasting author:Cheng year>=2024 has:code cite:both limit:5'`                 |
| `spec-json` | structured search spec generated from a complex request        | `uv run python -B $SKILL_DIR/scripts/search_bib.py --bib references.bib --spec-json '{"query":"mamba forecasting","filters":{"year_min":2024},"citation_mode":"both"}'` |
| `spec-file` | repeatable saved search workflow                               | `uv run python -B $SKILL_DIR/scripts/search_bib.py --bib references.bib --spec-file search.json`                                                                        |
| `preview`   | compact human-readable summary after JSON search output exists | `uv run python -B $SKILL_DIR/scripts/preview_bib_search.py --input results.json`                                                                                        |

Keep `search_bib.py` as the source of truth for parsing, filtering, scoring,
sorting, raw BibTeX preservation, and citation snippet generation. Treat
`preview_bib_search.py` as a renderer only.

## Required Inputs

Minimum inputs:

- path to one local `.bib` file
- either a compact `--query`, inline `--spec-json`, or saved `--spec-file`
- optional sort, limit, citation-mode, raw BibTeX, or returned-field preferences

Common search spec fields:

- `query`: free-text topic query
- `filters.year_min`, `filters.year_max`, `filters.years_in`, `filters.exclude_years`
- `filters.author_contains`, `filters.author_excludes`
- `filters.type_in`, `filters.exclude_type_in`
- `filters.has`, `filters.exclude_has`
- `filters.field_contains`, `filters.field_excludes`
- `sort`: `relevance`, `year_desc`, `year_asc`, or `title`
- `limit`: default 5 unless the user asks for more
- `return_fields`: fields to expose in the JSON result
- `include_raw_bib`: `true` only when the user asks for original entries or exact export
- `citation_mode`: `latex`, `typst`, `both`, or `none`

## Output Contract

When presenting results to the user, use this order:

1. Briefly state how many matches were found and which filters were applied.
2. List top matches with requested research fields.
3. Include LaTeX and/or Typst snippets when requested or useful.
4. Include raw BibTeX only when requested or materially needed.
5. If no entries match, suggest specific filter relaxations.
6. Surface the additive `meta.recency` report when recency matters, and the per-result `claim_support` block when `--claim` was supplied — always repeating its provenance caveat (lexical overlap is not proof of support).

For each selected entry, usually include:

- citation key
- title and optional shorttitle
- authors
- year and venue/journal/booktitle
- DOI and/or eprint when present
- the supporting fields that made the entry relevant, such as keywords,
  annotation, or a short abstract excerpt
- a provenance note when useful: local `.bib` matches and citation snippets are
  bibliography evidence, not proof that the paper supports a manuscript claim

If the user supplied compact filters, echo the interpreted filters when negation,
field filters, or mixed citation/export options could otherwise be ambiguous.

## Workflow

1. Identify the `.bib` file path. If multiple candidates exist, use the one the
   user named or ask one concise clarification only if choosing would be risky.
2. If `rtk` is available, use it only for model-facing exploration such as locating
   `.bib` files or inspecting representative fields.
3. Translate the request into a compact query or JSON search spec.
4. Run `search_bib.py` with `uv run python -B` and preserve the JSON output.
5. Optionally run `preview_bib_search.py` after JSON output exists.
6. Inspect the result payload before answering.
7. Report matches, citation snippets, raw entries, or empty-result recovery advice
   according to the output contract.

RTK fast path guidance:

- locate bibliography files with `rtk find . -name "*.bib"`
- inspect a representative slice with `rtk read /path/to/library.bib -l aggressive -m 80`
- confirm fields with `rtk grep "doi|keywords|annotation|eprint" /path/to/library.bib`
- do not wrap machine-readable `search_bib.py` JSON output with RTK compression

## Search Planning

Use these defaults unless the user says otherwise:

- research discovery request -> `sort: relevance`
- no explicit limit -> `limit: 5`
- no explicit field list -> return `key`, `title`, `shorttitle`, `author`, `year`,
  `venue`, `doi`, `eprint`, `keywords`, `annotation`, and `abstract`
- asks for "original", "full entry", or "bib" -> `include_raw_bib: true`
- asks for citation snippets in a mixed LaTeX/Typst workflow -> `citation_mode: both`

Supported compact operators include:

- `author:cheng`
- `year>=2024`, `year<=2025`, `year:2024`, `year:2023,2024`
- `type:article,misc`, `-type:misc`
- `has:code,doi`, `-has:pdf`
- `annotation:CodeAvailable`, `keywords:mamba`, `abstract:photovoltaic`
- `sort:year_desc`, `limit:10`, `fields:key,title,year,doi`
- `cite:latex`, `cite:typst`, `cite:both`, `cite:none`
- `raw:true`
- `recent:3` (recency window for the additive `meta.recency` report; or `--recent-window`)
- `claim:"..."` (adds per-result `claim_support`; prefer `--claim` for claims with spaces)

The useful `has` values are `doi`, `abstract`, `keywords`, `annotation`,
`shorttitle`, `eprint`, `pd