Oma Scholar

Scholar - Research Paper Sidecar Companion

Scheduling

Goal

Search, fetch, generate, validate, analyze, review, and compare scholarly paper sidecars using the Knows .knows.yaml spec for token-efficient research workflows.

Intent signature

• User asks for academic literature search, sidecar generation, sidecar validation, paper claims/evidence summary, structural paper comparison, or peer review as sidecar.
• User references Knows, .knows.yaml, knows.academy, OpenAlex, claims, evidence, relations, or paper sidecars.

When to use

• Reading research papers token-efficiently via Knows sidecars (~700 tokens for claims-only vs ~10K for full PDF)
• Generating .knows.yaml sidecars from your own paper drafts, LaTeX, or research notes
• Validating sidecar structure (rule-based) before sharing
• Producing peer reviews as sidecars
• Querying or summarizing existing sidecars
• Structurally comparing two papers (claims, methods, evidence)
• Searching/fetching sidecars from knows.academy (2026 papers only; current counts via /api/proxy/jobs/stats)

When NOT to use

• General web search or non-academic content -> use oma-search
• Translating papers -> use oma-translation
• PDF parsing only (no sidecar) -> use oma-pdf
• Submitting sidecars back to knows.academy -> out of scope (host LLM only consumes/produces locally)
• Full peer-review workflow with editor system -> out of scope

Expected inputs

• Paper, abstract, draft, LaTeX, research notes, sidecar file, DOI, OpenAlex ID, Knows record ID, or search query
• Desired mode: generate, validate, review, analyze, compare, or remote fetch
• Optional strictness, section filter, or CI behavior

Expected outputs

• .knows.yaml sidecar, review sidecar, lint report, search/fetch result, natural-language analysis, or structural comparison
• Sidecars conforming to v0.9.0 / paper@1 profile
• Validation status and warnings before sharing generated sidecars

Dependencies

• oma scholar CLI subcommands
• knows.academy public API; OpenAlex and Semantic Scholar fallbacks
• resources/sidecar-spec.md, API endpoints, OpenAlex setup, upstream cache, checklist, and execution protocol

Control-flow features

• Branches by mode, source availability, Knows/OpenAlex coverage, strict vs lenient validation, and fetched section
• Reads/writes YAML sidecars and may call public APIs
• Avoids fabrication when source evidence is missing

Structural Flow

Entry

1. Identify mode and source artifact/query.
2. Resolve paper identity through Knows or OpenAlex when needed.
3. Load sidecar spec and mode-specific protocol.

Scenes

1. PREPARE: Select mode and gather source or remote identifiers.
2. ACQUIRE: Fetch paper metadata, sidecar sections, or local source text.
3. REASON: Extract claims, evidence, relations, provenance, or comparison structure.
4. ACT: Generate, lint, review, analyze, compare, or fetch sidecar data.
5. VERIFY: Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator.
6. FINALIZE: Return sidecar, report, summary, or comparison with caveats.

Transitions

• If knows.academy lacks the paper, fall back to OpenAlex metadata/abstract.
• If generating a sidecar, run lint before sharing.
• If consuming third-party sidecars with dangling references, use lenient mode when appropriate.
• If source evidence is absent, omit fields instead of guessing.

Failure and recovery

• If remote API times out, retry or use OpenAlex fallback.
• If YAML fails parsing, fix indentation and scalar types.
• If relation density or orphan statements warn, review coverage and type-appropriate links. Preserve source-anchored questions/definitions; never add unsupported relations to satisfy a quota.

Exit

• Success: requested sidecar operation completes with validation status.
• Partial success: missing metadata, fallback source, or validation warnings are explicit.

Logical Operations

Actions

Tools and instruments

• oma scholar search|resolve|get|lint
• Knows public API, OpenAlex fallback, sidecar spec, checklist

Canonical command path

oma scholar search "<query>"
oma scholar resolve "<title-or-doi>"
oma scholar get "<record-id-or-doi>"
oma scholar lint "<paper.knows.yaml>"

Resource scope

Preconditions

• Mode and source are identifiable.
• Spec rules are available for generation or validation.

Effects and side effects

• May create local sidecar or review sidecar files.
• May query public scholarly APIs.
• Does not submit sidecars back to knows.academy.

Guardrails

1. Local generation targets v0.9.0 production compatibility / paper@1 (review sidecars use review@1). This is narrower than complete canonical schema conformance; see resources/sidecar-spec.md.
2. Host LLM generates sidecars: never shell out to anthropic SDK or external LLM CLI; this skill runs inside an agent
3. Anti-fabrication: if DOI/venue/year is not visible in source, omit the key entirely; never write doi: TODO or guess
4. Top-level metadata: title, authors, venue, year live at the top level (no metadata wrapper)
5. Field names are exact: statement_type, evidence_type, predicate, artifact_type (not type/claim)
6. Provenance has SINGLE actor: provenance.actor is one object, NOT a provenance.actors array
7. Confidence is an object: {claim_strength: ..., extraction_fidelity: ...}, both from high|medium|low
8. Coverage is an object: coverage.statements (4-value enum) + coverage.evidence (3-value enum)
9. Closed enums: actor tool|person|org (never ai/llm/model); artifact role subject|supporting|cited; predicates in present tense
10. Numbers unquoted: value: 22, never value: '22'
11. Relation coverage: review the local ratio/orphan warnings; add only source-supported, type-appropriate relations. Claims with evidence use supported_by; definitions and open questions can remain source-anchored. A ratio of 1.5 is diagnostic, not a graph-padding quota.
12. ID format: descriptive kebab-case with prefix: stmt:privacy-budget-tradeoff, ev:cifar10-accuracy-table, art:paper
13. Validate before sharing: run oma scholar lint after Generate and Review; cross-record refs (record_id#local_id) in review sidecars are recognized and not flagged as dangling
14. Remote API has no auth: https://knows.academy/api/proxy/* is public; do not invent auth headers
15. Partial fetch param is section (singular): fixed enum statements|evidence|relations|artifacts|citation
16. Fallback API keys are optional: OPENALEX_API_KEY (metadata enrichment) and S2_API_KEY (Semantic Scholar dedicated rate limit) both improve throughput but the cascade degrades gracefully without them
17. Sidecar content stays English: schema fields, IDs, statement text follow upstream convention; user-facing responses follow oma-config.yaml language
18. Contract scope: local generation rules and lint track production compatibility, not the complete canonical v0.9 schema. Preserve canonical imported shapes and report local-lint incompatibilities. Do not claim full schema compliance or add $schema without validation against that exact schema; see resources/upstream-spec-cache.md.