// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
= RSR Philosophy — The Estate's Operating Doctrine (canonical)
:toc: preamble
:icons: font

[.lead]
This is the *canonical* statement of the operating principles every hyperpolymath
repository is worked under. It is the source that `rsr-template-repo` operationalises
and that the estate arrival-pack projects, in summary form, into the top of every
`CLAUDE.md`. The owner's `manifesto` states the same doctrine in its own voice;
where wording must be reconciled, the manifesto prevails.

The principles are deliberately few and blunt. They describe not only *what* good
work is but the *order* and *manner* in which it is undertaken.

== Solutions at source

*Fix the canonical, upstream origin of a problem — never patch the downstream
symptom.*

When a defect, a drift, or a wrong setting appears in many places, it is almost
never many problems: it is one problem at a source, expressed many times.
Remediating the copies while leaving the source untouched guarantees the problem
returns — and worse, makes it look solved. The estate's own shape makes the source
explicit: `standards → rsr-template-repo → (every repo)`. A fix that belongs at the
template does not belong, hand-applied, in hundreds of leaves.

Two obligations follow, and neither is optional:

. *Find the source.* Before acting, trace the thing back to where it is actually
  defined — the template, the generator, the canon, the single point everything
  else inherits from — and fix it there.
. *Be mindful of every up- and down-stream.* A change at a source propagates.
  Before making it, know what feeds the thing you are changing (upstream) and what
  depends on it (downstream), and ensure the change is safe across all of them. A
  correct fix that breaks a downstream consumer is not yet a fix.

Where the source genuinely cannot be reached in one pass — an upstream you do not
own, a change gated on owner ratification — remediate the downstream *and* record
the source fix as the real work still owed. Silently patching the symptom as if it
were the cure is itself a soundness hole (see _fail loudly_).

This principle stands beside its two siblings: *holes before goals* and *always
fail loudly*. Together they govern the order of work (holes first), the manner of
work (loudly, never silently green), and the locus of work (at the source, never
the symptom).

== Holes before goals

Fix soundness holes before features, optimisation, or documentation. A hole is
anywhere the system can be wrong without saying so. Goals are everything one would
rather be doing. Let the holes set the agenda — a goal reached on top of a hole is
not reached.

== Always fail loudly

No silent green. A check that cannot fail is not a check; a fallback that hides a
broken precondition is a forged result. Seams (ABI / FFI) are sealed and proven,
not assumed. Prefer a build that breaks to a build that lies.

== The full Doctrine

The complete, always-current operating Doctrine is maintained as estate-common
content in the arrival-pack and projected into every repository's `CLAUDE.md`. In
addition to the three principles above it holds: ground-truth by running the tool,
not trusting status docs; distrust the neural for exactness (licences, invariants,
equivalence belong to PLASMA, not an LLM); squabble, don't bypass (reach green by
satisfying the gate, never by admin-override); no automated licence edits; no
deletion by access-recency; wire first; always sign; report faithfully (no
overclaim); stop-first on costly or outward-facing actions; boundaries are real;
and equivalence as identity.

== See also

* `hyperpolymath/manifesto` — the doctrine in the owner's voice.
* `hyperpolymath/rsr-template-repo` — `RSR-PHILOSOPHY.adoc` and the arrival-pack
  that projects the Doctrine summary into every `CLAUDE.md`.
