Skip to content

Commit d2ce2dc

Browse files
Peter Higginsclaude
Peter Higgins
and
claude
committed
Add HUF User Handbook (HUF-HB-001)
Quick reference + guided links into the full document set. Covers: MC-4, CoDa foundation, EITT, chemistry trilogy, shadows/orthogonal views, tools, governance, and a Category Discovery Checklist (11-step decision tree). All file references verified against restructured repo. README updated with handbook as top Start Here entry. ChatGPT drafted, Claude corrected file paths and integrated. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b4c501d commit d2ce2dc

2 files changed

Lines changed: 287 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ HUF/
7070

7171
| Time | What | Where |
7272
|------|------|-------|
73+
| 15 min | **User Handbook** — fast summary + guided links into the full document set | [`science/core/HUF_USER_HANDBOOK.md`](science/core/HUF_USER_HANDBOOK.md) |
7374
| 5 min | What HUF is, in plain language | [`science/core/WHAT_HUF_IS.md`](science/core/WHAT_HUF_IS.md) |
7475
| 10 min | The EITT finding and the numbers | [`science/core/EITT_Finding.md`](science/core/EITT_Finding.md) |
7576
| 15 min | Full explanation with CoDa mathematics | [`science/core/EITT_CODA_MATHEMATICS.md`](science/core/EITT_CODA_MATHEMATICS.md) |

‎science/core/HUF_USER_HANDBOOK.md‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Higgins Unity Framework — User Handbook
2+
**DocCode:** HUF-HB-001
3+
**Title:** HUF User Handbook (Quick Reference + Guided Links)
4+
**Version:** 1.1
5+
**Status:** Draft "state of record" (handbook track)
6+
**Date:** 2026-04-11
7+
**Maintainer:** Higgins Unity Framework Collective
8+
9+
---
10+
11+
## Purpose
12+
13+
This handbook is the *fast path* into HUF: a readable overview that lets a new reader:
14+
1) understand what HUF is trying to do,
15+
2) learn the key terms *without* reading everything at once, and
16+
3) jump from any brief topic to the deeper "source" document(s).
17+
18+
> **Design intent:** keep the *context* flowing and human-readable; keep the *math* compact and boxed inside "Analytic" panels.
19+
20+
---
21+
22+
## How to use this handbook
23+
24+
### If you only have 15 minutes
25+
1) Read **What HUF Is** → then **The Four Monitoring Categories**.
26+
2) Skim the category descriptions below.
27+
3) Pick *one* deep-dive path: **Math (CoDa)** or **Chemistry (EITT/PRISM)**.
28+
29+
### If you're building or auditing systems
30+
Follow the links in each section and keep notes on:
31+
- **Frame**: what is being measured and in what coordinate system?
32+
- **Invariants**: what must remain true under transformation?
33+
- **Shadows**: what projections reveal what the full object hides?
34+
- **Actuation**: what interventions close the loop?
35+
36+
---
37+
38+
## Start here (core orientation)
39+
40+
- **What HUF Is (plain-language overview)**
41+
→ [`science/core/WHAT_HUF_IS.md`](WHAT_HUF_IS.md)
42+
43+
- **The Core (foundational concepts)**
44+
→ [`science/core/THE_CORE.md`](THE_CORE.md)
45+
46+
- **EITT Finding (what the method sees in practice)**
47+
→ [`science/core/EITT_Finding.md`](EITT_Finding.md)
48+
49+
- **EITT + CoDa Mathematics (formal backbone)**
50+
→ [`science/core/EITT_CODA_MATHEMATICS.md`](EITT_CODA_MATHEMATICS.md)
51+
52+
- **Complete Explanation (the full narrative)**
53+
→ [`science/core/EITT_Complete_Explanation.md`](EITT_Complete_Explanation.md)
54+
55+
- **Formula Reference (all key equations)**
56+
→ [`science/core/FORMULA_REFERENCE.md`](FORMULA_REFERENCE.md)
57+
58+
---
59+
60+
## The Four Monitoring Categories
61+
62+
> Think of HUF as a *multi-frame measurement standard*. The first three categories are universally deployed. The fourth — composition monitoring — is the one HUF proposes.
63+
64+
| Category | Name | Question | Status |
65+
|----------|------|----------|--------|
66+
| MC-1 | Magnitude Monitoring | How much? | Universally deployed |
67+
| MC-2 | Identity Monitoring | Who or what? | Universally deployed |
68+
| MC-3 | Trend Monitoring | Which direction? | Universally deployed |
69+
| **MC-4** | **Composition Monitoring** | **What is the balance?** | **Proposed (HUF)** |
70+
71+
### MC-1, MC-2, MC-3 (the established three)
72+
These are the monitoring categories every domain already uses. They answer magnitude, identity, and trend. They are necessary but insufficient — they can miss structural redistribution that changes the system's character without changing its headline totals.
73+
74+
### MC-4: Composition Monitoring (HUF's proposal)
75+
**What it is:** monitoring the internal proportional balance of a system's parts as a primary observable.
76+
**Why it matters:** it exposes **ratio blindness** — when people treat relative quantities as if they were absolute, or miss redistribution that headline totals don't show.
77+
78+
**Read more:**
79+
- [`science/core/WHAT_HUF_IS.md`](WHAT_HUF_IS.md)
80+
- [`drafts/codawork-2026/MC4_ISO_Positioning_Document.docx`](../../drafts/codawork-2026/MC4_ISO_Positioning_Document.docx)
81+
82+
---
83+
84+
## CoDa: The Mathematical Foundation
85+
86+
**Compositional Data Analysis (CoDa)** is the mathematics of ratios where "parts of a whole" live on the simplex. HUF does not claim new CoDa mathematics — it claims a monitoring application built on the Aitchison framework.
87+
88+
Key concepts: closure, log-ratio transforms (ilr/alr/clr), Aitchison distance, simplex geometry.
89+
90+
**Read more:**
91+
- [`science/core/EITT_CODA_MATHEMATICS.md`](EITT_CODA_MATHEMATICS.md)
92+
- [`science/core/FORMULA_REFERENCE.md`](FORMULA_REFERENCE.md)
93+
- [`drafts/codawork-2026/EITT_CoDa_Cheatsheet.pdf`](../../drafts/codawork-2026/EITT_CoDa_Cheatsheet.pdf)
94+
- [`drafts/codawork-2026/HUF_MC4_CoDaWork_Packet_v3.pdf`](../../drafts/codawork-2026/HUF_MC4_CoDaWork_Packet_v3.pdf)
95+
96+
---
97+
98+
## EITT in one page
99+
100+
**EITT (Entropy Invariance under Temporal Transformation):** Shannon entropy appears empirically near-invariant under geometric-mean block decimation of compositional time series.
101+
102+
Measured: **0.18% variation** across a 341:1 compression ratio (daily → annual European electricity compositions). Confirmed across energy, hardware, cosmology, commodities, and chemistry (500,000 data points).
103+
104+
### The Chemistry Extension (April 2026)
105+
106+
Four diagnostic lenses applied to chemical mixture data:
107+
108+
| Lens | Best Region | Key Finding |
109+
|------|------------|-------------|
110+
| Raw Shannon | Interior (54–82% pass) | Interior standard; curvature diverges at boundary |
111+
| Jensen-corrected | Neither (overcorrects) | Taylor expansion diverges on global traversals |
112+
| Rényi q=2 | Marginal improvement | Wrong curvature order for the simplex |
113+
| Aitchison norm | Boundary (closes gap from 16% to 2.5%) | Uniform curvature; the CoDa metric works |
114+
115+
**Read more:**
116+
- [`science/chemistry/EITT_Chemistry_Findings.docx`](../chemistry/EITT_Chemistry_Findings.docx) — raw science, four-lens table, failure taxonomy
117+
- [`science/chemistry/HUF_Development_Index.docx`](../chemistry/HUF_Development_Index.docx) — what residuals mean, domain distance from ground zero
118+
- [`science/chemistry/PRISM_Chemistry_Analysis.docx`](../chemistry/PRISM_Chemistry_Analysis.docx) — ranked resource allocation targets
119+
- [`science/chemistry/chem_eitt_pipeline.py`](../chemistry/chem_eitt_pipeline.py) — the pipeline (open source, runs on a laptop)
120+
121+
---
122+
123+
## Three frameworks from the chemistry work
124+
125+
| Framework | What It Does | Document |
126+
|-----------|-------------|----------|
127+
| **EITT Findings** | Raw science. Four-lens results, failure taxonomy, multi-modal simplex | [`EITT_Chemistry_Findings.docx`](../chemistry/EITT_Chemistry_Findings.docx) |
128+
| **HUF-IDX** | Development index. What residuals mean. Domain distance from ground zero | [`HUF_Development_Index.docx`](../chemistry/HUF_Development_Index.docx) |
129+
| **PRISM** | Operational layer. Ranked resource allocation targets from residual analysis | [`PRISM_Chemistry_Analysis.docx`](../chemistry/PRISM_Chemistry_Analysis.docx) |
130+
131+
---
132+
133+
## Key idea: Shadows, orthogonal views, and "seeing shape"
134+
135+
A **shadow** is a projection of the full system onto a reduced frame where:
136+
- the signal becomes simpler,
137+
- invariants become visible, and
138+
- confounds become separable.
139+
140+
In CoDa language, a shadow can be a log-ratio coordinate view (ilr/alr/clr) or a projection along an Aitchison-orthogonal basis.
141+
142+
### How do we infer shape from shadows?
143+
Use a **probe-and-rotate** routine:
144+
145+
1) **Define the frame**: choose what "counts as a part," and choose the closure (what sums to 1).
146+
2) **Choose probe contrasts**: pick log-ratio contrasts that correspond to real hypotheses.
147+
3) **Rotate basis**: change coordinate frames to see which features are invariant.
148+
4) **Compare shadows**: if multiple projections agree, you've found structure. If they disagree, you've found hidden coupling or a frame error.
149+
150+
**Read more:**
151+
- [`science/core/EITT_CODA_MATHEMATICS.md`](EITT_CODA_MATHEMATICS.md)
152+
- [`science/methodology/COMPOSITIONAL_GOVERNANCE_SCALE.md`](../methodology/COMPOSITIONAL_GOVERNANCE_SCALE.md)
153+
154+
---
155+
156+
## Tooling (when you want repeatability)
157+
158+
| Tool | Purpose | Location |
159+
|------|---------|----------|
160+
| Chemistry EITT pipeline | Run EITT on compositional data | [`tools/pipeline/chem_eitt_pipeline.py`](../../tools/pipeline/chem_eitt_pipeline.py) |
161+
| HUF preparsers | Parse energy, backblaze, and general data | [`tools/pipeline/`](../../tools/pipeline/) |
162+
| Spectrum Analyzer | Interactive visualization | [`tools/spectrum-analyzer/`](../../tools/spectrum-analyzer/) |
163+
| Diagnostics | Validation, dashboards | [`tools/diagnostics/`](../../tools/diagnostics/) |
164+
165+
---
166+
167+
## Governance, confidence, and scale
168+
169+
These documents translate "insight" into "controlled use":
170+
171+
- **HUF Governance Charter**
172+
→ [`huf-gov/HUF_GOVERNANCE_CHARTER.md`](../../huf-gov/HUF_GOVERNANCE_CHARTER.md)
173+
174+
- **Confidence Index**
175+
→ [`science/methodology/CONFIDENCE_INDEX.md`](../methodology/CONFIDENCE_INDEX.md)
176+
177+
- **Compositional Governance Scale**
178+
→ [`science/methodology/COMPOSITIONAL_GOVERNANCE_SCALE.md`](../methodology/COMPOSITIONAL_GOVERNANCE_SCALE.md)
179+
180+
- **Kill Test (19 documented failure modes)**
181+
→ [`huf-gov/governance/KILL-001-kill-test.json`](../../huf-gov/governance/KILL-001-kill-test.json)
182+
183+
**Protocol:** HUF-GOV. Measure, report, file. No intervention on the data.
184+
185+
---
186+
187+
## Category Discovery Checklist
188+
189+
Use this when you suspect **ratio blindness**, projection effects ("shadows"), or stale mappings are hiding *real* structure. The goal is to decide whether your current category set is (a) sufficient, (b) missing one or more categories, or (c) using the right categories but the **wrong frame**.
190+
191+
### 1) Define the observation set
192+
- What are you trying to explain (phenomenon, boundary, time scale)?
193+
- What data is "in-bounds" vs "out-of-bounds" for this pass?
194+
- Write the **current category mapping** you're using (even if you think it's wrong).
195+
196+
### 2) Audit the measurement layer (before theory)
197+
- Units, normalization, and reference baselines (what is held constant?).
198+
- Missingness, censoring, and known confounds.
199+
- Are you mixing *levels* (individual vs group, local vs global) without an explicit bridge?
200+
201+
> **Analytic:** Category discovery fails most often at the measurement layer. If the baseline or normalization is drifting, you'll "discover" phantom categories that are just instrument movement.
202+
203+
### 3) Do a closure check on existing categories
204+
- Can the current categories reproduce the observations **without** ad-hoc exceptions?
205+
- Identify "residual structure": what's left over after the best-faith mapping?
206+
207+
> **Analytic:** If your residuals are *structured* (repeatable shape, phase lag, regime dependence), you're not done. If they're *unstructured* (noise-like), you may already have closure.
208+
209+
### 4) Run an orthogonal view sweep (shadow hunting)
210+
- Re-express the same situation in at least **3 frames** (different axes / viewpoints).
211+
- Track what stays invariant vs what appears/disappears under rotation.
212+
- Anything that looks "magical" often becomes ordinary in a better frame.
213+
214+
Practical prompts:
215+
- "What would I call this if I wasn't allowed to use the current category names?"
216+
- "What's the simplest *projection* that would create this apparent pattern?"
217+
218+
### 5) Perform a ratio audit (anti-ratio blindness)
219+
- List the **key ratios** the system implies (cost/benefit, signal/noise, input/output, gain/loss).
220+
- Rewrite in log space where useful (ratios become differences).
221+
- Look for ratios that remain stable across contexts — those are candidates for anchors.
222+
223+
### 6) Fixed-pole (anchor) test
224+
Treat categories as coordinate choices around **fixed poles**: reference points that remain stable while everything else moves.
225+
- Identify 1-2 anchors that do *not* change under the transformations you care about.
226+
- If you can't find anchors, you may be missing a category **or** your frame is misaligned.
227+
- If anchors exist, use them to define the "frame rails" for the rest of the mapping.
228+
229+
> **Analytic:** In the meromorphic analogy: fixed poles are structural constraints. They don't *explain* everything — they *pin* the allowable explanations.
230+
231+
### 7) Filter / phase / frequency scan (time-scale discovery)
232+
When a category is missing, it often shows up as a **time-scale** you didn't model.
233+
- Look for delays, phase flips, hysteresis, resonance, "ringing," overshoot/undershoot.
234+
- Separate fast dynamics (impulse response) from slow dynamics (drift / adaptation).
235+
236+
> **Analytic:** A clean way to spot hidden structure is to ask: "What frequency band is this effect living in?" Distinct bands often imply distinct categories or subcategories.
237+
238+
### 8) Probe with controlled perturbations
239+
- Change one input at a time (or simulate doing so) and predict the response using current categories.
240+
- Where predictions fail consistently, log the *conditions* of failure (regimes).
241+
242+
### 9) Propose the smallest new category that collapses residuals
243+
- Add **one** candidate category at a time.
244+
- Prefer categories that:
245+
- reduce exceptions,
246+
- improve cross-domain portability,
247+
- and preserve the anchors from Step 6.
248+
249+
### 10) Validate across domains (integration test)
250+
- Does the new category help in *another* domain without breaking the old one?
251+
- If it only helps in one narrow corner, it might be a *feature* or *parameter*, not a category.
252+
253+
### 11) Record + reconcile (machine track vs human track)
254+
- **Trace (machine):** update mappings, invariants, tests, and "why this category exists."
255+
- **Manual (human):** explain the intuition, examples, and cultural interpretability.
256+
- Add a glossary term and a doc index stub so the discovery is searchable and teachable.
257+
258+
### Quick "go / no-go" signals
259+
- **Go (likely new category):** structured residuals, stable anchors, repeatable failure regimes, distinct time-scale behavior.
260+
- **No-go (frame issue):** residuals vanish under rotation, ratios stabilize after renormalization, anchors emerge after redefining baselines.
261+
- **Stop (data issue):** effects track measurement drift, sampling artifacts, or mixed levels without a bridge.
262+
263+
---
264+
265+
## Glossary (living; extend as needed)
266+
267+
- **Actuation:** Intervention/control step that changes the system, ideally under governance.
268+
- **Aitchison geometry:** Geometry for compositional data; distances/angles in the simplex.
269+
- **Closure:** Normalization of components to a constant sum (often 1).
270+
- **CoDa:** Compositional Data Analysis; ratio-based reasoning.
271+
- **Contrast:** A log-ratio comparison between parts (a hypothesis encoded as a coordinate).
272+
- **EITT:** Entropy Invariance under Temporal Transformation; Shannon entropy near-invariant under geometric-mean block decimation.
273+
- **Fixed pole:** An invariant anchor/boundary that stays stable across transformations.
274+
- **Frame:** A coordinate system + assumptions defining what is measurable/meaningful.
275+
- **HUF-IDX:** HUF Development Index; measures a domain's distance from ground zero via EITT residuals.
276+
- **MC-4:** Monitoring Category 4; composition monitoring as a primary observable.
277+
- **PRISM:** Post-Residual Investigation for System Maturation; converts diagnostic residuals into ranked resource allocation targets.
278+
- **Ratio blindness:** Mistaking relative quantities for absolute ones; ignoring compositional constraints.
279+
- **Shadow:** A projection of a higher-dimensional structure into a simpler frame that reveals invariants.
280+
281+
---
282+
283+
**DocCode:** HUF-HB-001
284+
**Path:** `science/core/HUF_USER_HANDBOOK.md`
285+
**Status:** Draft (handbook track)
286+
**Keywords:** HUF, handbook, overview, index, CoDa, EITT, PRISM, MC-4, HUF-IDX, shadows

0 commit comments

Comments
 (0)