v0.1.3 · 23 skills · 15 hooks · 5 agents · MIT
Every claim in the draft cites a source, or prints [?][unresolved citation].
A ruleset and hooks for writing papers with Claude Code in LaTeX + BibTeX. It won’t write a citation it can’t resolve, and it won’t call a draft done while one is missing.
Copies the kit into the current project. macOS and Linux, Node 18+.
1 Introduction. The draft states only what its sources support [1]. A fake-shaped DOI or a .bib entry with an empty author field is refused before it is written [2]; a \cite key with no entry is reported on the next edit [3], and the turn cannot end while it stands [4]. This kit has caught a fabricated citation in a real manuscript before submission [?][unresolved citation].
Citation gate FAILED: undefined \cite keys (not in any .bib): sample:caught-before-submission Completion will be blocked by stop-gate.sh until resolved.
The last sentence has no source, so it prints [?][unresolved citation]. The log lines are citation-gate’s own; the key is a sample.
1The cardinal rule
Every claim traces to a real source. Never invent a citation, DOI, quote or quantity, and never claim more than the evidence supports [1]. In code a hallucination breaks the build. In a manuscript it looks correct, and can survive to print.
Without the kit
With the kit
Without the kitInvents a citation, DOI, author or page number that looks real.
With the kitRefuses a fake-shaped DOI or an empty required .bib field before it is written [2].
Without the kitCites a key that no entry in references.bib defines.
With the kitReports every undefined
\citekey on the next edit, and blocks completion until it resolves [3][4].Without the kitStates a statistic or measured value it doesn’t have.
With the kitWrites
[CITE]or[VALUE — verify]and reports the gap [5].Without the kitSays “causes” where the evidence licenses “is associated with”.
With the kitMatches each verb and quantifier to what the cited source says [6].
Without the kitPads sections with fluent filler before the evidence is in.
With the kitRestates the claim, gathers the evidence, then drafts the smallest passage that makes the point [7].
2The core loop
For every substantive piece of writing: Question → Evidence → Draft → Verify → Cite [7].
Question
Restate what the section must establish, as a claim a reader could dispute.
Evidence
Gather the sources first. If they aren’t in references.bib or sources/, say so.
Draft
Write the smallest passage that makes the point, in the surrounding voice.
Verify
Run the verification order below.
Cite
Every non-trivial claim carries a \cite{key} that resolves to a real entry.
Before a section is done, in this order [8]
- 1.Citations resolve
- 2.Quotes match, with a locator
- 3.Claims are supported
- 4.Numbers are consistent
- 5.Cross-references resolve
- 6.Compiles clean
- 7.Gaps are counted, not hidden
Steps 1, 5 and 6 are checked by hooks [3][9]. Steps 2–4 still need a human or /claim-check: a hook can’t read the source PDF for you.
3The hooks
15 shell hooks run on Claude Code events [10]. 5 of them can stop a tool call or the end of a turn; the rest report back into the conversation.
- SessionStartsession-startreportsLoads the thesis, target venue, active task and branch state into context.
- UserPromptSubmitprompt-routerreportsAdds a reminder when a prompt touches causal claims, statistics, citations or a reviewer response.
- PreToolUse · Edit|Write|NotebookEditprotect-sourcesblocksRefuses edits to sources/, submitted/, data/raw/ and any *.frozen.* file.
- PreToolUse · Edit|Write|NotebookEditblock-fabricationblocksRefuses a fake-shaped DOI or a .bib entry with an empty required field.
- PreToolUse · Bashbranch-protectblocksRefuses a direct push to main or master.
- PreToolUse · Bashblock-dangerous-commandsblocksRefuses shell commands that are hard to undo.
- PostToolUse · Edit|Write|NotebookEditunicode-scanreportsWarns about invisible Unicode characters that can hide text or code in a file.
- PostToolUse · Edit|Write|NotebookEditcitation-gatereportsChecks that every \cite key has a .bib entry and every \ref has a \label.
- PostToolUse · Edit|Write|NotebookEditcompile-gatereportsReads the LaTeX log for undefined citations, undefined references and compile errors.
- PostToolUse · Edit|Write|NotebookEditword-budgetreportsWarns when a section grows past the word budget declared at its top.
- PostToolUse · Edit|Write|NotebookEditai-tellreportsFlags phrasing that reads as machine-written, so the author can rewrite it.
- PostToolUse · Edit|Write|NotebookEditfigure-orphanreportsWarns about figures never referenced, unused image files and missing graphics.
- Stopstop-gateblocksRefuses to end the turn while the citation or compile gate has failed.
- SessionEndsession-endreportsAppends one line per session to the audit log that /scorecard reads.
- SessionEndjournal-foldreportsFolds the session’s notes and agent handoff into a handoff file for the next session.
ResearchKitBench: 37/37 scenarios pass, run at build time [11].
4Skills and agents
23 slash commands and 5 subagents for the work a hook can’t do: reading a claim against its source, or reviewing a draft the way a referee would.
Audits 7
- /citation-audit
Dangling \cite keys, orphan .bib entries, duplicates and bad DOIs
- /claim-check
Classifies each claim in a section and checks its citation supports the wording
- /gap-finder
Finds unsupported and uncited claims across a whole draft
- /journal-fit
Scope, length, structure and reference style against a target venue
- /methods-review
Could someone reproduce this from the Methods section alone?
- /scorecard
Turns the session audit log into a per-session table
- /stats-check
Bare p-values, missing effect sizes and causal overclaim in Results
Workflows 11
- /abstract
Drafts the abstract so every number in it appears in the body
- /cover-letter
An editor cover letter from the manuscript map
- /literature-review
Related work from your own library: references.bib, sources/ and the vault
- /manuscript-cycle
Runs the whole loop, from outline to submission checks
- /outline
A thesis and a venue in, a claim-per-section IMRaD outline out
- /peer-review
A simulated review by the peer-reviewer and integrity-reviewer agents
- /plain-language-summary
A lay summary for a funder, a journal or a general reader
- /reference-format
Converts the bibliography to the venue’s citation style
- /response-to-reviewers
A point-by-point reply that says what changed and where
- /retro
A retrospective on what got written and what reviewers kept raising
- /submission-pipeline
Every review agent and audit, run once before you submit
Literature vault 3
- /lit-briefing
What changed in the vault since your last session
- /lit-ingest
Reads one source into the vault as a summary page
- /lit-lint
Contradictions between sources and pages with no .bib entry
Kit 2
- /note
Writes a finding or decision to the session journal so it survives compaction
- /review-resurface
Brings back past reviewer notes that apply to the current task
Agents 5
- fact-checker
Checks each claim in the manuscript against its source
- integrity-reviewer
Looks for overclaiming, p-hacking and selective reporting
- outline-planner
Plans the argument: one claim per section and the evidence for it
- peer-reviewer
Reviews the draft the way a tough, fair referee would
- vault-maintainer
Does the heavy lifting of ingesting sources into the vault
5Field overlays
The core rules are discipline-neutral. An overlay adds a field’s reporting standards and reviewer expectations. Switch one on with a line in CLAUDE.project.md [12].
## Field overlay - Active overlay: `agent_docs/field/ai-ml.md`
- ai-ml
AI / ML / NLP (with an LLM-agents emphasis)
NeurIPS · ICML · ACL
- life-sciences
Life Sciences / Biology (wet-lab, omics, animal & observational)
ARRIVE · STROBE · PRISMA
- medicine
Clinical / Medical Research
CONSORT · STROBE · SPIRIT
- social-sciences
Social Sciences (psychology, sociology, econ-adjacent)
APA 7 · OSF · Registered Reports
6Why not just prompt carefully?
A prompt asks. A hook checks.
“Don’t invent citations” in a prompt is advice the model can lose three turns later. A hook runs on every edit whether the model remembers or not: a fake-shaped DOI is refused [2], an undefined key is reported [3], and the turn can’t end until it’s fixed [4].
Other tools get the rules, not the hooks.
CLAUDE.md is the single source. ./scripts/convert.sh derives AGENTS.md, Cursor rules, .windsurfrules and Aider’s CONVENTIONS.md from it [13]. Those tools read the same discipline, but nothing enforces it there: the hooks are Claude Code’s.
References
- [1]CLAUDE.md, § Source-Grounded Writing (the cardinal rule).
- [2].claude/hooks/block-fabrication.sh, PreToolUse hook.
- [3].claude/hooks/citation-gate.sh, PostToolUse hook.
- [4].claude/hooks/stop-gate.sh, Stop hook.
- [5]agent_docs/citation-discipline.md, § The placeholder protocol.
- [6]CLAUDE.md, § Claim Discipline.
- [7]CLAUDE.md, § The Core Loop.
- [8]CLAUDE.md, § Verification (Mandatory Order).
- [9].claude/hooks/compile-gate.sh, PostToolUse hook.
- [10].claude/settings.json, hooks.
- [11]scripts/run-bench.sh, ResearchKitBench runner.
- [12]CLAUDE.project.md, § Field overlay.
- [13]scripts/convert.sh.
Install it in the project you’re writing.
The next section Claude drafts there is held to the cardinal rule.
Copies the kit into the current project. macOS and Linux, Node 18+.
Or as a Claude Code plugin: