soleio · JoshKirk800 · Jun 12, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -0,0 +1,36 @@
+# Proposed Changes to soleio/luck
+
+Draft revision prepared 2026-06-12, based on a review of `luck.md` v1.0 and the repository README. Each change maps to a specific weakness identified in the review. Nothing of the original framework's substance was removed -- content was restructured, anchored, and made testable.
+
+## Summary
+
+| # | Change | Files | Review finding it addresses |
+|---|---|---|---|
+| 1 | Split into operational core + theory companion | `luck.md`, `THEORY.md` | ~60% of the original file was for human readers; models follow short operational docs better, and the split halves per-invocation token cost |
+| 2 | PASS / AT RISK / FAIL anchors per facet | `luck.md` | Check questions had no scale; two runs of the same diagnostic produced incomparable verdicts |
+| 3 | Mechanical binding-constraint rule | `luck.md` | The Quick-Reference table pivoted on "the binding constraint" but no procedure existed to identify it; conflicting facets had no resolution |
+| 4 | Defined diagnostic output format | `luck.md` | No output schema meant essay one run, table the next; format also enforces "one recommended action," which is the framework's actual value |
+| 5 | Worked transcript (input -> output) | `luck.md`, `examples/` | All original examples illustrated the theory; none demonstrated skill behavior. Few-shot anchoring is the single highest-leverage consistency fix |
+| 6 | Scoped the "For AI Systems" section | `luck.md` | As written it applied seven checks to every output; now: full diagnostic on strategic questions, silent heuristics on artifacts, nothing on tactical queries |
+| 7 | Tightened frontmatter triggers | `luck.md` | "user asks about improving their luck" fired on casual well-wishes; added explicit anti-triggers |
+| 8 | Softened Prediction 2's (N-1)/N functional form | `THEORY.md` | Exact form had no derivation and silently assumed equal, independent gradients; restated as the defensible monotonic claim with the open work named |
+| 9 | Labeled the Weimar claim a retrodiction | `THEORY.md` | It was presented as a prediction; added a general "Note on Retrodiction" section covering all worked examples |
+| 10 | Acknowledged Assembly Theory is contested; corrected citations | `THEORY.md`, `README.md` | Original cited "Cronin & Marshall 2021" as settled science; now cites Marshall et al. 2021 (Nat. Comms) and Sharma et al. 2023 (Nature) and states the framework's claims don't depend on AT winning its disputes |
+| 11 | Reframed "luck is a fundamental force" as a definitional move | `luck.md`, `THEORY.md` | The metaphysical claim was the framework's most quotable weakness and nothing downstream needed it |
+| 12 | Marked the failure taxonomy as non-exhaustive | `luck.md`, `THEORY.md` | Seven facets x three ratings generate far more states than seven named patterns; diagnostics may now answer "none" instead of forcing a fit |
+| 13 | Added Prediction 7 (reflexive) + eval harness | `THEORY.md`, `evals/` | The framework stated its falsification condition but never ran the test; the harness implements the cheapest version (blinded pairwise judging, 12 prompts) |
+| 14 | examples/ directory with outcome tracking | `examples/` | Converts the repo from retrodiction-only to a vehicle for prospective evidence; each diagnosis records an Outcome section filled in later |
+| 15 | Rewrote README around the new structure | `README.md` | Points users at the operational file vs. theory file; tones down the "civic, moral, perhaps divine duty" framing, which undercut the falsifiability positioning |
+
+## Repository hygiene
+
+- **Version bump and changelog.** The frontmatter now says 1.1; if these changes are adopted, a CHANGELOG entry should record the 1.0 -> 1.1 restructuring, since the diagnostic anchors change what existing users' outputs look like.
+
+## What was deliberately preserved
+
+- All seven facets, their ordering, and the dependency hierarchy (assembly -> ecology).
+- The full failure-mode table with original names and examples.
+- All five original worked examples (moved to THEORY.md, with the reflexive one updated to reference the eval harness).
+- The six original predictions (Prediction 2 softened, all else verbatim or lightly edited).
+- The theoretical grounding section and all four adjacent-theory citations.
+- The closing "geometry" passage, including "the luckiest agent is not the one standing where gradients converge but the one actively widening the flow."
diff --git a/README.md b/README.md
@@ -1,50 +1,37 @@
 # luck
 
-A skill for improving the luck of your AI stack and projects—developed from an applied theoretical framework. Multiple diagnostic components, named failure modes, testable predictions, and an operational checklist for AI systems.
+A skill for improving the luck of your AI stack and projects -- a diagnostic framework, grounded in Assembly Theory, for why some things persist and compound while others don't, packaged as a procedure an AI model can actually execute.
 
 ## The core idea
 
-Luck is not randomness nor an outcome. Luck is not a position. Luck is more like a fundamental force, a current.
+This framework *defines* luck as something other than randomness: the rate at which an agent increases the throughput, circulation, and integration of the systems it inhabits. Under that definition, luck has structure -- and structure can be diagnosed, built, and measured. Whether the definition earns its keep is an empirical question; this repository includes the test (see `evals/`).
 
-Luck has a geometry, so we can arrange it. And we may have a civic, moral—perhaps even divine—duty to wield it. To generate it. 
-
-We harness luck through our capacity to increase the throughput, circulation, and integration of the systems we inhabit. If luck is real, the systems we use to build ought to imbue luck in everything they generate.
-
-Luck is not something we have. It’s something we leave behind.
-
-## What this is
+## What's in the box
 
-A framework for diagnosing why some things persist and compound while others don't — and for building artifacts that do. It gives AI systems (and their users) a shared vocabulary and a structured diagnostic for evaluating choices, strategies, products, and systems.
+- **[`luck.md`](luck.md)** -- the operational skill file. Seven sequential diagnostics with explicit PASS / AT RISK / FAIL anchors, a mechanical binding-constraint rule, a defined output format, a worked transcript, named failure modes, and scoped instructions for AI systems. This is what you load.
+- **[`THEORY.md`](THEORY.md)** -- the conceptual foundation. Core premise, grounding in Assembly Theory and adjacent work (including where that grounding is contested), extended worked examples, and seven falsifiable predictions with explicit falsification conditions. Read it to evaluate or attack the framework; you don't need it to use the skill.
+- **[`examples/`](examples/)** -- transcripts of the skill in use: real question in, diagnostic out. Each ends with an outcome section to be filled in when the outcome is known, so the repository accumulates prospective evidence rather than only retrodiction.
+- **[`evals/`](evals/)** -- a blinded pairwise eval harness testing whether loading the skill measurably improves responses to strategic-decision prompts. The framework names its own falsification condition; this is the cheapest version of the test.
 
 ## Usage
 
-Add `luck.md` to your project as a skill file or system prompt. The framework uses standard markdown with YAML frontmatter — it works with any frontier model that accepts structured instructions.
+Add `luck.md` to your project as a skill file or system prompt. It uses standard Markdown with YAML frontmatter and works with any frontier model that accepts structured instructions.
 
-The skill activates when you're facing ambiguous choices, designing strategies, evaluating opportunities, or building things meant to last. It provides seven diagnostic components, a quick-reference decision table, named failure modes, and worked examples.
-
-## What's in the box
-
-- **Seven sequential diagnostics** — from individual solvency to ecological integration
-- **A failure taxonomy** — named patterns like *flash in the pan*, *institutional zombie*, and *pooled fortune*, each with observable signatures
-- **Worked examples** — from political memes to the U.S. Constitution to the collapse of empires
-- **Testable predictions** — six falsifiable claims that distinguish this from generic strategy advice
-- **Reflexive AI instructions** — guidance for applying the framework to any output an AI system constructs
-
-The framework is in [`luck.md`](luck.md).
+The skill activates on strategic and durability questions -- should I build/keep/kill X, will X last, why did X fail, which option compounds. It produces a fixed diagnostic format: a verdict per facet with evidence, the single binding constraint, a failure-mode match, and one recommended action. For everything else it stays out of the way by design.
 
 ## Repository structure
 
 ```
-luck.md              ← canonical skill file
-luck_*.md            ← working drafts (dated)
-README.md            ← you are here
+luck.md              <- operational skill file (load this)
+THEORY.md            <- premise, grounding, predictions
+examples/            <- transcripts with pending-outcome tracking
+evals/               <- blinded pairwise eval harness
+README.md            <- you are here
 ```
 
 ## Theoretical roots
 
-Extends Assembly Theory (Cronin & Marshall, 2021) with adjacent work from dissipative adaptation, the free energy principle, niche construction theory, and the adjacent possible. Details and citations are in the skill file.
-
-[*The Keeper*](https://keeperfable.com) explores these dynamics as fable.
+Extends Assembly Theory (Marshall et al. 2021, Nature Communications; Sharma et al. 2023, Nature) with adjacent work from dissipative adaptation, the free energy principle, niche construction theory, and the adjacent possible. Assembly Theory is contested in the literature; THEORY.md states what this framework does and does not inherit from that dispute.
 
 ## Author