Start from an outside view

A reference class is a collection of past cases selected by a stated inclusion rule. It counters the tendency to focus entirely on the vivid details of the current case. Its value depends on the denominator: which attempts were included, which were omitted, and which have not resolved.

Record the class definition, inclusion rule, data source, observation window, successes, failures, unresolved cases, and transfer concerns. reference::ReferenceClass keeps these fields together and checks the declared counts for overflow.

Empirical and smoothed rates

If there are k successes and f failures, the empirical rate is k / (k + f). Unresolved cases are reported separately; they are not added as failures. No resolved cases means that an empirical rate is unavailable.

A Beta prior with parameters alpha and beta produces a posterior with parameters alpha + k and beta + f. Its mean is a next-case probability under the exchangeability assumption. The prior parameters are modeling choices, not observed extra cases.

extern crate supercast;
use supercast::bayes::BetaPrior;

let posterior = BetaPrior::new(1.0, 1.0)?.observe(12, 40)?;
assert!((posterior.mean().get() - 13.0 / 42.0).abs() < 1e-12);
assert!(posterior.variance() > 0.0);
Ok::<(), supercast::Error>(())

The reference_class JSON operation returns both the empirical rate and the smoothed posterior summary. With no resolved cases, empirical_rate is null while the supplied Beta prior still has a defined mean. That is a prior-driven estimate, not a historical success rate.

Three kinds of uncertainty

Distinguish sampling uncertainty from uncertainty about class selection and from structural change. More historical cases may reduce sampling noise without answering whether the class applies to the current setting. A product release by an experienced team may belong to a different class from a first release on a new platform.

When reasonable class definitions disagree, show their results separately. Overlapping classes are not independent evidence sources. Averaging them without accounting for overlap can make the record appear broader than it is.

Skewed quantities

For cost, duration, and capacity, retain the distribution’s tail. An empirical quantile is often more useful than a symmetric percentage band. Supercast uses linear interpolation at index (n - 1) * q, commonly called type 7:

extern crate supercast;
use supercast::{Probability, reference::quantile};

let mut duration_ratios = [1.0, 1.1, 1.2, 1.5, 4.0];
let p80 = quantile(&mut duration_ratios, Probability::new(0.8)?)?;
assert!((p80 - 2.0).abs() < 1e-12);
Ok::<(), supercast::Error>(())

The function sorts the supplied slice in place. P80 is a quantile of that empirical distribution, not an 80% confidence interval around its mean. Sampling design and transfer concerns still belong in the report.