ontology-from-paper

name	ontology-from-paper
description	The full ontology authoring workflow as a single skill. Take a topic or source paper, research it, extract concepts/relations/axioms, scaffold the ontology with define_ontology!, scaffold candidate functors and adjunctions to existing related ontologies, run the laws check, run gap analysis, and report. Produces a draft for human review — does not auto-commit.

ontology-from-paper

The closing-loop skill. Composes most of the other skills in this directory to take pr4xis from "a topic to encode" to "a tested, integrated draft ontology" in one invocation.

When to invoke

When the user wants to add a new domain to pr4xis from a published source paper (or set of papers). This skill is the operationalization of the principle "every ontology is grounded in research, encoded as code, and verified by tests".

This is the most ambitious skill in the directory. The first few runs will need substantial human review of the generated draft. Treat its output as a starting point, not finished work.

Inputs

• Required: a topic name (e.g., propulsion-cycles, enzyme-kinetics, pregroup-grammar-extensions)
• Optional: a source paper DOI, arXiv ID, or local PDF path
• Optional: a list of related existing ontologies the new one should compose with (e.g., ["natural/physics", "applied/space/orbit"])
• Optional: a target branch under crates/domains/src/ (e.g., applied, natural, formal). If not specified, the skill will infer from the topic.

Workflow

1. Research

If no source paper is supplied:

• Use web search (Google Scholar, arXiv, BioPortal, etc.) to find candidate papers for the topic
• Surface the top 3-5 candidates with title, author, year, venue, and abstract
• Stop and ask the user to confirm which paper(s) to use. Do not proceed without explicit approval.

If a source paper is supplied: skip to step 2.

2. Extract

Read the approved paper(s) end to end. Extract structured knowledge:

• Named concepts → candidate Entity enum variants (use the paper's terminology verbatim where possible)
• Stated relationships → candidate rows for the relevant reasoning systems:
  • Is-a statements → taxonomy rows
  • Part-of statements → mereology rows
  • Causes statements → causation rows
  • Opposes / contrasts → opposition rows
• Stated invariants → candidate Axiom impls (each with the paper citation)
• Stated quantities → candidate Quality types (with units)
• Context-dependent definitions → candidate ContextDef entries
• Cited prior work → candidate citings.md entries

3. Scaffold the ontology directory

Create crates/domains/src/<branch>/<topic>/:

• ontology.rs — the define_ontology! block, the Entity enum, the Relation type
• tests.rs — structural law tests (auto-generated by define_ontology!) plus property-based tests for each domain axiom
• mod.rs — wiring
• papers/ — directory containing the source paper PDF(s) if a local copy was supplied or downloaded

Then add the new module to the parent mod.rs.

4. Generate the per-ontology pack

Invoke per-ontology-rollout on the new ontology directory to generate:

• README.md (via per-ontology-readme)
• citings.md (via per-ontology-citings) — the source paper from step 1 should be the primary entry
• Internal mermaid diagram (via per-ontology-mermaid-internal)
• External mermaid diagram (via per-ontology-mermaid-external — initially empty, filled in by step 6)

5. Verify the encoding compiles

Run cargo check -p pr4xis-domains and cargo test -p pr4xis-domains <topic>::tests. The structural axioms (category laws, taxonomy NoCycles, mereology WeakSupplementation, etc.) are auto-generated and should pass on a well-formed ontology. If they fail, surface the failure and stop.

6. Find candidate functors

For each ontology in the workspace that:

• Shares concept names with the new one (grep), OR
• Was listed by the user as a related ontology in step 0, OR
• Is in a "neighboring" branch (e.g., a new biomedical ontology gets functors checked against existing biomedical ontologies)

…invoke functor-author to scaffold a Functor: New → Existing and a Functor: Existing → New. Each scaffold produces a draft; the todo! cases are surfaced for human review.

7. Verify the functors compile and pass laws

For each generated functor, run cargo test -p pr4xis-domains <functor_name>. If the functor has todo! cases, the test will panic — that's expected, surface it for the human. If the functor compiles fully and the laws fail, that's a structural mismatch — report which morphism breaks the laws.

8. Find candidate adjunctions

For each pair of generated functors going in opposite directions between the same two ontologies, invoke adjunction-author to scaffold the adjunction.

9. Run gap analysis

For each generated adjunction, invoke the existing analyze_* function in crates/domains/src/formal/meta/gap_analysis.rs (or the test that runs it). Report the unit-loss and counit-loss percentages and the entities that collapse. Each collapse is a candidate missing distinction in one of the ontologies — surface it for human consideration of a ContextDef resolution.

10. Run the full workspace test

cargo test --workspace. If any pre-existing test that used to pass now fails, the new ontology has introduced a contradiction with an existing one. Surface the conflict, do not auto-fix.

11. Report

Produce a structured summary:

• Path of the new ontology directory
• Source paper(s) cited
• Number of entities encoded, broken down by category
• Number of axioms encoded
• Number of functors generated, with confidence levels (high / medium / TODO)
• Number of adjunctions generated
• Gap-analysis results for each adjunction
• Workspace test result (passed / pre-existing failures / new failures)
• Outstanding todo! cases for the human to resolve
• Suggested next steps (which todo!s to fill in first, which gaps to investigate, etc.)

Then stop. Do not commit. The user reviews and commits.

Rules

• Never proceed without an approved source paper. If the user supplies one, use it. If not, search and ask. Do not invent ontologies from thin air.
• Never skip the laws check. Every functor and adjunction must pass check_functor_laws (or todo! out the unfilled cases honestly). Do not commit a functor that fails the laws.
• Never overwrite existing ontologies. If crates/domains/src/<branch>/<topic>/ already exists, refuse and ask. Pick a different topic name or update the existing one explicitly.
• Surface every todo! in the final report. The user must know what's incomplete before they commit.
• Do not try to verify the draft against the literature. The skill produces a draft; literature verification is human work.

Failure modes

• No paper found for the topic: surface the search results that didn't match and ask the user to either supply a paper or refine the topic
• Paper is paywalled and no local PDF supplied: report the DOI/URL and ask the user to obtain the PDF
• Extraction step misses concepts: the user reviews the draft and adds the missing entities — this is expected, the skill is conservative
• Pre-existing tests start failing: report the conflict with the specific failing test, do not roll back the new ontology — the human investigates whether the conflict is a bug in the new encoding or a reveal that an existing ontology was wrong

Notes

This skill is the headline use case for the project. When it works well, it makes adding a new domain to pr4xis a one-command operation. When it fails, the failures are educational — they tell the user where the structural assumptions of pr4xis disagree with the real-world domain, which is exactly the kind of friction that makes a categorical substrate worth using.

Expect the first 5-10 invocations to produce drafts that need substantial human revision. Each invocation also improves the skill itself (failure cases reveal where the inference rules are too aggressive or too conservative).