per-ontology-citings

name	per-ontology-citings
description	Generate a citings.md file for one pr4xis ontology directory by extracting source-paper citation comments from the surrounding code. Produces a structured bibliography with full citations, DOIs/URLs, and one-line annotations of which axioms each source grounds. Where the code references a paper without a full bibliography entry, scaffold a placeholder for human filling.

per-ontology-citings

Generate a citings.md file for one pr4xis ontology directory. Pioneers the citings.md naming convention from issue #57.

When to invoke

When an ontology directory has source citation comments scattered through its ontology.rs, tests.rs, or sibling files (e.g., // Source: Alberts et al., MBoC 6th ed.) but no consolidated citings.md. Or when the existing citings.md is stale relative to the code.

This is one of four sibling skills for the per-ontology rollout. The wrapper per-ontology-rollout invokes this one alongside per-ontology-readme, per-ontology-mermaid-internal, and per-ontology-mermaid-external.

Inputs

• Required: the absolute path to an ontology directory under crates/domains/src/
• Optional: a flag to overwrite an existing citings.md (default: refuse and ask)

What to read

1. Every .rs file in the ontology directory and its subdirectories. Look for citation patterns:

   • Doc comments containing Source:, Reference:, Cited:, cf., e.g.,
   • Author-year patterns inside doc comments: Coste et al. 2010, Alberts (2015), [Lambek 1958]
   • URL or DOI patterns inside comments: https://doi.org/..., arXiv:...
   • // Source: markers that this project uses by convention
   • #[doc = "..."] annotations with paper references

2. docs/papers/references.md — the workspace-wide bibliography. For each citation extracted from the ontology, check whether a full entry exists in references.md. If yes, link to it. If no, scaffold a placeholder.

3. The doc comment on the define_ontology! block itself — often contains the primary source for the whole ontology

4. Any existing papers/ subdirectory in the ontology directory — local PDFs that should be cited alongside the workspace-wide ones

5. Any existing citings.md if one exists — preserve manually-added entries, only regenerate the auto-derivable parts

What to write

A <ontology-dir>/citings.md with this structure:

# Citings — <Ontology Display Name>

Every published source this ontology stands on. Each entry includes the full citation, a DOI/URL where available, and one-line annotation of which concepts, axioms, or relations the source grounds.

This is the per-ontology bibliography. The workspace-wide bibliography of all sources cited by all ontologies lives at [`docs/papers/references.md`](../../../../docs/papers/references.md).

## Primary sources

<For each major source paper that grounds the whole ontology or a substantial section:>

### <Author Year — Title>

- **Full citation**: <APA/Chicago/etc., one line>
- **DOI**: <doi> or **URL**: <url> or **Local PDF**: `papers/<filename>.pdf` (if a local copy exists in this ontology's papers/ directory)
- **Grounds**: <one-line description of which concepts, axioms, or relations come from this source>
- **Cited at**: `ontology.rs:<line>`, `tests.rs:<line>`

## Supporting sources

<For minor / supporting references — same format but compressed:>

- <Author Year>: <one-line>. <link>. Grounds: <what>.

## Pending verification

<Sources that the code mentions but the skill could not find a full bibliography entry for. Each one is a TODO for the human to fill in:>

- **<author-year-shortname>** — referenced in `ontology.rs:<line>` but no full citation found in `references.md` or `papers/`. Verify and add.

---

- **Document date:** <today's ISO date>
- **How this file is maintained**: source citations live in code comments; this file is generated by the `per-ontology-citings` skill from those comments. To add a new citation, add a `// Source: ...` comment in the relevant Rust file and re-run the skill, or add the entry directly here.

Rules

• Every citation must be sourceable. If you can't find a full bibliography entry in references.md or in the local papers/ directory, put it in the "Pending verification" section, don't fabricate one.
• Preserve manual edits. If the existing citings.md has entries the code doesn't reference, keep them. The human may have added them manually.
• One-line annotations are mandatory. Every entry needs a "Grounds:" line saying what specifically this paper provides. If you can't tell from the code, mark it "Grounds: TBD — verify against source".
• Use relative paths to local PDFs. If papers/sola_2017_quaternion_kinematics.pdf exists in the ontology directory, link to it as papers/sola_2017_quaternion_kinematics.pdf, not as an absolute path.
• No marketing language, no superlatives. Citations are plain bibliographic entries.

Verification before declaring success

1. The new citings.md exists and is non-empty
2. Every entry has Author, Year, Title, and a "Grounds:" line
3. Every "Cited at:" line points to a real file:line that actually contains the reference (verify by reading the file at that line)
4. Every local PDF reference points to a file that actually exists in the papers/ subdirectory
5. The "Pending verification" section is non-empty if and only if there are codereferences that lack full bibliography entries
6. The cross-link to docs/papers/references.md resolves (the file exists)

Output

Report a summary with:

• Path of the new citings.md
• Number of primary sources extracted
• Number of supporting sources
• Number of pending-verification entries (TODOs for the human)
• Anything that needs human attention (e.g., "Coste et al. 2010 is referenced 3 times in the molecular biology comments but not in references.md — please add the full bibliography entry")

Failure modes

• No citations found in the code: the ontology doesn't cite its sources. This is a problem per the project's "research first" memory. Surface it as a warning and produce an almost-empty citings.md with a note that the ontology has no documented sources and should not have been written this way.
• Source comments use inconsistent formats: some say "Source: X", others say "cf. Y", others use bare author-year. Extract all of them; normalize in the output.
• A code reference looks like a citation but isn't: e.g., // see issue #45. Skip non-paper references. Only extract things that look like academic sources.
• The workspace-wide references.md is itself stale or missing entries: report the gaps, but don't rewrite references.md from this skill — that's a separate concern.

Notes

This is the first instance of the citings.md convention from #57 being applied uniformly. The skill is intentionally simple: it extracts what's in the code, formats it consistently, and surfaces gaps for the human to fill in. It does not invent citations. It does not download PDFs. It does not search the web.

For the broader "find papers for a new ontology" workflow, see research-paper-find when that skill exists, or the ontology-from-paper skill which composes both.