diff --git a/RSR-PHILOSOPHY.adoc b/RSR-PHILOSOPHY.adoc new file mode 100644 index 00000000..342d87cb --- /dev/null +++ b/RSR-PHILOSOPHY.adoc @@ -0,0 +1,78 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += 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`.