Rigor Type Oracle

Rigor Type Oracle

You are about to write a type. Stop and ask Rigor first.

This project has a deterministic type oracle installed. Reading the source and concluding "currency is a String, pattern is a Regexp" is plausible-guess behaviour: it is right often enough to feel safe and wrong often enough to poison a signature file, a doc comment, or a reviewer's mental model. Rigor already knows the answer — for every expression, at every line, from the same engine that will check the code tomorrow. Asking it costs one command.

The rule: a type you did not obtain from Rigor is a guess, and a guessed type is never written anywhere. Not in sig/, not in an inline annotation (#:, # @rbs), not in a Sorbet sig, not in a YARD tag, not in a doc sentence, not in a review comment, and not as the stated reason for a nil check or an is_a? guard.

First: load the version-current copy

This skill's exact commands, flags, output spellings, and skip-reason ids drift between Rigor releases, so follow the copy that ships with the installed Rigor rather than any vendored or frozen copy of this file. Get the complete current procedure in one call:

rigor skill --full rigor-type-oracle   # this body + all its references/, inline

If you already loaded this skill via rigor skill you have the current copy — just proceed (read any references/NN-*.md from the directory the header names). If rigor is not on PATH, this task needs it: run rigor-next-steps to install Rigor first, then come back.

When to use

Trigger on the act, not on the user saying the word "type". You are in scope the moment you are about to write or assert one:

• Writing or editing RBS under sig/.
• Writing an inline annotation — rbs-inline #:, # @rbs, a %a{rigor:v1:…} override.
• Writing a Sorbet sig do … end, or any other type DSL.
• Writing a YARD / RDoc @param / @return / @raise, or any doc sentence that names a type ("returns an Array of entries").
• Stating a type in a review comment, a PR description, or a chat answer.
• Justifying a nil check, an is_a? / respond_to? guard, or a defensive to_s with "this should be an X".
• Being asked "what type is this?", "what does this method return?", "add types to this class", "document this file".

When NOT to use

• Setting Rigor up on a project that has none → rigor-next-steps (which routes to rigor-project-init). You cannot ask an oracle that is not installed.
• Working an existing .rigor-baseline.yml down → rigor-baseline-reduce. That is fixing diagnostics, not sourcing a type.
• Raising type protection from a coverage --protection list → rigor-protection-uplift. It owns the "where should a type go, and how do I verify it" loop; this skill owns "where does the type itself come from".

The three allowed sources

Every type you write comes from exactly one of these. There is no fourth.

The parameter row is the one genuine gap. Inference reads a method body, and a body does not state what its callers are allowed to pass — so Rigor spells parameters untyped by design (ADR-5: strict on returns, lenient on parameters). --params=observed derives them from the call sites instead, which is evidence rather than invention — but it is narrow evidence (it can emit literal types such as ("JPY")), so it is the one place you review and widen before adopting, under the gate that rigor check gains no new diagnostic.

Exact command forms, flags, position syntax, JSON shapes, and how to read each output: references/01-oracle-commands.md.

The gap protocol — a gap is a finding, not a blank to fill

Dynamic[top], untyped, and a sig.skipped.* classification are answers. They mean "Rigor cannot prove a type here", which is information about the project or about the engine. Filling that hole with your own reading converts a known unknown into a confident falsehood, and it does so in a file the next reader will trust.

So when the oracle comes back empty:

1. Report it. Give the exact command and its exact output.
2. Find out why, when it matters: rigor trace --format=json --line=N FILE replays how the type was built; rigor explain <rule> documents a diagnostic that fired nearby.
3. Route it. A project-side gap has a sibling skill that closes it (missing gem RBS → rigor-rbs-setup; an unconfigured framework → rigor-plugin-tune; the project's own monkey-patches → rigor-monkeypatch-resolve; a project DSL → rigor-plugin-author). An engine-side gap is a Rigor issue.

Which output means which gap, the full routing table, and how to word the issue: references/03-gap-protocol.md.