Scholar Ontology

this skill

Distil what a corpus calls things into a type hierarchy, a controlled vocabulary, and an evidence layer. The product is a study directory, not a document, and every claim in it either cites a pinned source or carries a command that reproduces its number.

Read references/evidence-tiers.md before starting; it decides what each claim must carry. references/citation.md governs every pin. references/stage-gates.md states each stage's exit condition.

User arguments: $ARGUMENTS

Core thesis

An agent that has read a corpus usually returns a summary. A summary cannot be checked, does not compose, and rots without saying so.

The test this pipeline is built against:

CAN A READER WHO WAS NOT PRESENT DISAGREE WITH A CLAIM,
FIND WHAT IT RESTS ON, AND RE-DERIVE IT?

A study that fails that test is a summary with more sections.

Context

Repository — run this command and read the output:

git remote get-url origin 2>/dev/null || echo "(not a git repository)"

Current ref — run this command and read the output:

git rev-parse --short HEAD 2>/dev/null || echo "(unknown)"

Existing studies — run this command and read the output:

ls notes/ontology/ 2>/dev/null || echo "(none)"

Stages

Five stages, run in order. Each is separately invocable, so a study resumes where it stopped rather than restarting.

1. the scholar-gather skill — resolve and pin the corpus, inventory it, and record what was read and what was skipped, into sources.jsonl.
2. the scholar-extract skill — harvest the terms the corpus uses, with a citation and a locator each, into terms.jsonl.
3. the scholar-distill skill — build the three layers: types, members with discriminators, and the controlled vocabulary.
4. the scholar-contest skill — judge the ontology adversarially, one candidate at a time, recording the kills.
5. the scholar-render skill — write brief.md and the evidence documents, and gate the brief.

For prose, run the scholar-annotate skill before extract to produce quotations with stable locators.

--resume=<stage> starts at that stage against an existing study directory.

Orchestration Plan

Enter plan mode before touching anything — EnterPlanMode in Claude Code, /plan or Shift+Tab in Cursor, Codex, and Gemini. Where plan mode is unavailable, present the same plan in chat and wait.

The plan states:

• The corpus: each target, its resolved ref, and how it was resolved.
• The kind — code, prose, or fleet — and what that changes about stages 1 and 2.
• The output directory, and confirmation that it is not inside the corpus.
• Which stages will run, and which are being skipped because a prior study already satisfies them.
• The coverage boundary: what will deliberately not be read, and why.

Present it, wait for approval, then exit plan mode and run stage 1.

Rules

• Never write into the corpus being studied. Output lands under --out, defaulting to notes/ontology/<subject>/ in the current repository.
• Every claim carries a tier. A claim that fits neither tier does not go in the brief.
• The brief carries no citation, no permalink, and no bare number. Where it wants one, it links into evidence/.
• A stage may not hand off until its gate passes. Report a failed gate; do not work around it.
• Terms are recorded as the corpus spells them. Variants are the evidence, not noise to normalize away.
• The analyzer proposes; it never decides. Every finding gets a human or agent verdict recorded in evidence/contested.md.

Output

Open with a one-line hero (✓ <subject>: <n> terms, <n> types, <n> contested or ⚠ Blocked: <reason>), then exactly these sections:

1. ## Corpus — each source, its resolved ref, and what was deliberately not read, with the reason.
2. ## Ontology — the type hierarchy in prose, each type with its discriminator, and the vocabulary's preferred terms.
3. ## Contested — what was challenged and how it resolved, including what was killed and what the kill revealed.
4. ## Where it lives — the study directory path and which stages ran.

End with an ask-user-choice panel offering next steps (for example: contest another round, compare against another study, publish the brief, stop here) — skip the panel only in plan mode.

Portability notes

• ask-user-choice — present the listed options and wait for the user to pick one. Hosts with a structured multiple-choice tool (Claude Code's AskUserQuestion) should use it; otherwise print a numbered list and wait for a numbered reply. Never proceed on an assumed answer.
• $ARGUMENTS — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none.
• Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.