Simplify skill.md

Author: mathpluscode

.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "bibtools",
       "source": "./",
       "description": "A bibliography toolkit for LaTeX",
-      "version": "1.7.5",
+      "version": "1.7.6",
       "keywords": ["bibtex", "bibliography", "latex", "overleaf", "academic", "reference", "citation"],
       "category": "academic",
       "license": "MIT"

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bibtools",
   "description": "A bibliography toolkit for LaTeX",
-  "version": "1.7.5",
+  "version": "1.7.6",
   "author": {
     "name": "Yunguan Fu"
   },

README.md

@@ -63,6 +63,8 @@ Or in Claude Code, use the slash command: `/bibtidy refs.bib`
 
 bibtidy verifies each entry against [Google Scholar](https://scholar.google.com/) and [CrossRef](https://search.crossref.org/), fixes errors, and upgrades stale preprints to published versions. Every change includes the original entry commented out above so you can compare or revert, plus one or more `% bibtidy:` URL lines for verification. We recommend using git to track changes. If using [Overleaf](https://www.overleaf.com/), this can be done with [git sync](https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization). To remove bibtidy comments after review, ask your agent to remove all `bibtidy` comments from the file.
 
+bibtidy's output is non-deterministic: the same `.bib` file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry. See the [FAQ](#bibtidy) for why, and always verify changes via the `% bibtidy:` URLs before accepting them.
+
 Note that bibtidy assumes standard brace-style BibTeX like `@article{...}`. Parenthesized forms like `@article(...)` are not supported. Special blocks such as `@string`, `@preamble`, and `@comment` are ignored by the parser.
 
 ### How it works
@@ -408,6 +410,16 @@ bibtidy needs to search Google Scholar, CrossRef, and conference/journal sites.
 
 You shouldn't, and that's by design. The point of bibtidy is to surface potential hallucinations and errors in your bibliography. For every changed entry, bibtidy includes a `% bibtidy:` URL so you can verify the correction yourself. Entries marked unchanged are very likely correct, but not guaranteed. Always check the provided links before accepting changes.
 
+**Why do I get different results on different runs, or between Claude Code and Codex?**
+
+bibtidy is non-deterministic. Running it twice on the same `.bib` file can produce different fixes, and Claude Code and Codex may reach different conclusions on the same entry. There are a few reasons for this:
+
+- Search results vary between queries. Google Scholar and CrossRef can return slightly different candidate sets for the same title, and the web itself changes over time as new publications, DOIs, and venue pages appear.
+- Agent decisions depend on LLM sampling, which is stochastic. Given ambiguous evidence (e.g. a preprint with a near-match published version), different runs may land on `fix`, `review`, or `unchanged`.
+- Claude Code and Codex use different underlying models with different tool surfaces, so their web-search behavior and judgment thresholds differ.
+
+This is why every change ships with `% bibtidy:` URLs: you should treat bibtidy's output as a reviewed first draft, not a final answer. Re-running on an already-tidied file is safe, and a second pass sometimes catches issues missed in the first.
+
 **How does bibtidy compare to other tools?**
 
 [CiteAudit](https://arxiv.org/abs/2602.23452) verifies bibliographic metadata but is a closed system. bibtidy is fully open-source, transparent (every change includes the original entry commented out and a source URL so you can verify exactly what changed and why), and it fixes issues (wrong authors, stale preprints, incorrect pages) directly in your .bib file rather than just flagging them.

docs/build.py

@@ -473,6 +473,8 @@ def build_html(cards_html: str) -> str:
 <div class="container">
 <p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
 
+<p class="intro"><strong>Note:</strong> bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+
 <div class="section">
   <div class="demo">
     <img src="bibtidy_demo.gif" alt="bibtidy demo" width="1600" height="1200">

docs/index.html

@@ -268,6 +268,8 @@ <h1>bibtools</h1>
 <div class="container">
 <p class="intro">bibtidy cross-checks BibTeX entries against Google Scholar, CrossRef, and conference/journal sites. It upgrades arXiv/bioRxiv preprints to published versions (even when the title changed upon publication), corrects metadata (authors, pages, venues), and flags duplicate entries.</p>
 
+<p class="intro"><strong>Note:</strong> bibtidy's output is non-deterministic. The same <code>.bib</code> file can yield different fixes across runs, and Claude Code and Codex may reach different conclusions on the same entry, due to variability in search results, LLM sampling, and differences between the two agents' underlying models. Every change ships with <code>% bibtidy:</code> URLs for verification &mdash; treat the output as a reviewed first draft, not a final answer.</p>
+
 <div class="section">
   <div class="demo">
     <img src="bibtidy_demo.gif" alt="bibtidy demo" width="1600" height="1200">

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bibtools"
-version = "1.7.5"
+version = "1.7.6"
 description = "A bibliography toolkit for LaTeX, built as agent skills"
 requires-python = ">=3.10"
 license = "MIT"