Ontology From Paper

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).