diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..0b0b402 --- /dev/null +++ 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 index 8a1a566..f52ee79 100644 --- 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 diff --git a/THEORY.md b/THEORY.md new file mode 100644 index 0000000..937a8c3 --- /dev/null +++ b/THEORY.md @@ -0,0 +1,90 @@ +# The Geometry of Luck: Theory + +This file contains the conceptual foundation for the operational diagnostic in [luck.md](luck.md). It is written for human readers and for anyone who wants to evaluate, extend, or attack the framework. You do not need it to run the diagnostic. + +----- + +## Core Premise + +The universe does not select for complexity in the abstract. It selects for complexity that can sustain its own pattern against dissipation. An assembly that cannot harness enough energy to hold itself together disappears regardless of its elegance. An invasive species that collapses the ecology sustaining it perishes with it. This is true of molecules, organisms, institutions, and markets -- the principle is thermodynamic before it is economic. + +But persistence alone does not explain why complexity increases. The direction of complexity is toward configurations that increase their own metabolic throughput through ecological coupling -- and this process has a hierarchy. Individual assemblies must be solvent. Solvent assemblies couple to gradients. Coupling creates structures through which energy and capability circulate. Circulation sustains integration across systems. And integration density determines the assembly index an ecology can reach. Bands of tribes with a common language are not a civilization. Bands of tribes connected by trade routes, political pacts, legal codes, and shared infrastructure are -- because each integration structure increases the total throughput of the network, generating the surplus that makes the next integration structure possible. + +Complexity does not produce integration. Integration produces complexity. The arrow of desire -- the tendency of solvent systems to evolve toward greater ecological throughput through deeper coupling -- traces this path. + +### On the word "luck" + +This framework uses "luck" as a *defined term*, not a metaphysical discovery. We define luck as the rate at which an agent increases the throughput, circulation, and integration of the systems it participates in -- a vector with direction and magnitude, not an outcome one receives. The claim being made is pragmatic: that the cluster of properties this definition picks out (surplus capacity, gradient diversity, circulation rate, integration density, niche construction) predicts persistence and compounding better than the colloquial notion of luck-as-randomness, and better than single-variable alternatives. That claim is testable, and the Measurement section below states what would falsify it. Readers who prefer to mentally substitute "structural fortune" or "persistence capacity" for "luck" lose nothing. + +----- + +## Extended Worked Examples + +### Low assembly, high compatibility, no niche construction + +A political meme -- an image macro juxtaposing a public figure with a situational caption. Assembly index is minimal: one image, one cultural reference, one comedic frame. Reconstruction cost is near zero, so it spreads instantly. But it constructs no niche. It cannot generate demand for itself beyond the initial context. Its gradient (topical attention) is non-renewing. Diagnosis: flash in the pan. The structural fortune is entirely positional -- the right node in the right network at the right moment. The luck is real but non-compounding. + +### High assembly, self-sustaining, niche-constructing + +The U.S. Constitution. Assembly index is enormous -- it requires prior assembly of English common law, Enlightenment philosophy, colonial governance experience, the specific failures of the Articles of Confederation, and political compromises among competing factions. But it exhibits the self-sustaining property: it creates courts, legislatures, amendment processes, and legal pedagogy that generate continuous demand for constitutional interpretation. Each successful governance outcome reinforces the institutional ecology. Gradient pluralism is strong -- it couples to legal, political, educational, and cultural throughput simultaneously. Its luck compounds structurally. + +A retrodiction the framework offers (a post-hoc reading, not a prediction -- see the note on retrodiction below): constitutions of comparable intellectual quality, such as Weimar Germany's or various post-colonial constitutions, failed not because the ideas were worse but because the surrounding assembly ecology could not sustain their persistence -- the gradient coupling or institutional niche construction was insufficient. This reading is consistent with the framework; it is not evidence for it. Evidence would require the kind of out-of-sample tests described under Measurement. + +### Integration as the threshold of civilization + +Bands of tribes may share language, sophisticated tool-making, social hierarchy, and deep ecological knowledge. The assembly index within each tribe can be substantial. But each tribe is a closed circulatory system -- knowledge, resources, and capability flow within it but not between tribes in any structured way. Common language lowers the cost of coupling but does not create the structures of coupling. Two tribes that can talk are not integrated. Two tribes connected by a trade route they both depend on and maintain are the beginning of integration. Add a shared grazing agreement, a marriage alliance with kin obligations, a seasonal gathering with rituals neither group can perform alone -- each is a circulatory structure through which throughput flows between systems. Each one, once established, lowers the cost of the next. A trade route creates conditions for a trade agreement. A trade agreement creates conditions for standardized measures. Standardized measures create conditions for taxation. Taxation creates conditions for infrastructure. Infrastructure creates conditions for law. This is the arrow of desire operating at the inter-system level: each integration structure increases total throughput, generating the surplus that makes the next structure possible. The civilization's assembly index emerges from the density of circulatory connections between its parts. + +### Circulation failure: empires that collapse from the edges + +Empires do not fail from their center. They thin at the periphery. Roads are maintained less, garrisons supplied less, local officials supervised less. The circulation structures go quiet. Without active flow, the integration at the edges decays, and the periphery reverts to the assembly index it can sustain on its own -- the region, the tribe, the local chieftain. The most fragile point was never the most complex assembly (the capital, the court, the legal code). It was the most critical circulatory bottleneck -- the road, the supply line, the communication channel that kept the periphery coupled to the whole. + +### The reflexive case: this framework + +This skill is itself an assembly entering an ecology. Its solvency depends on whether it produces measurably better outputs when used -- if it does, it sustains continued attention; the eval harness in `evals/` exists to test exactly this. Its gradient coupling targets AI-assisted decision-making, a renewing and expanding flow. Its compatibility is designed to be high: it follows existing skill-file conventions and uses a sequential checklist with explicit anchors that requires no prior theoretical knowledge. Its niche construction bet is that the vocabulary (solvency, circulation, integration density, binding constraint) becomes useful shorthand that creates demand for the framework itself. Its circulation test: does the framework flow outward from this document into other contexts -- conversations, decisions, designs -- and return as improved practice and contributed examples? Its integration test: does it connect domains that were previously siloed -- thermodynamics and strategy, ecology and business, physics and fortune? + +----- + +## A Note on Retrodiction + +Every worked example above is a retrodiction: a historical case read through the framework after the outcome is known. Retrodictions demonstrate that the framework can be *applied*; they do not demonstrate that it *predicts*. Any sufficiently flexible framework can accommodate known outcomes. The framework's claim to be more than generic strategy advice rests entirely on the predictions below and on prospective use -- diagnoses made before outcomes are known, recorded, and scored. Users who want to contribute evidence should record diagnoses at decision time (the `examples/` directory shows the format) and revisit them. + +----- + +## Measurement and Falsifiability + +The framework makes testable predictions that distinguish it from generic strategy advice. + +**Prediction 1: Solvency dominates.** Among artifacts with comparable assembly indices, those with higher surplus capacity will show longer persistence and wider adoption than those with stronger gradient coupling but thinner margins. Test via: startup survival data correlated with burn rate vs. market size; open-source project longevity correlated with maintainer capacity vs. GitHub stars; ecosystem persistence correlated with net energy surplus vs. species diversity. + +**Prediction 2: Metabolic reach predicts resilience.** Artifacts coupled to more independent gradients should survive single-gradient shocks at higher rates, with survival probability increasing monotonically in the number of independent gradients. (We state the monotonic form only. A precise functional form would require assumptions -- equal gradient sizes, independent shocks -- that real systems violate; deriving the shape of the curve under realistic assumptions is open work.) Test via: company survival rates after industry disruptions, correlated with revenue stream diversity. + +**Prediction 3: Niche construction separates compounding from linear growth.** Artifacts exhibiting niche construction (adoption creates further demand) should show accelerating influence curves (superlinear growth), while those without should show linear or decelerating curves. Test via: technology adoption S-curves segmented by presence/absence of ecosystem effects. + +**Prediction 4: Circulation rate predicts system health better than aggregate throughput.** Systems with high total throughput but low circulation (pooled resources, stagnant flow) should show higher fragility and faster decline than systems with lower total throughput but active circulation. Test via: economic resilience correlated with velocity of money rather than GDP; ecosystem resilience correlated with nutrient cycling rate rather than total biomass. + +**Prediction 5: Integration density predicts maximum achievable assembly index.** The most complex artifacts in any domain should emerge from the most densely integrated ecologies, not from the most individually capable agents. Test via: patent complexity correlated with regional collaboration density; species complexity correlated with ecosystem interconnectedness; cultural output correlated with trade network density. + +**Prediction 6: Failure mode classification is diagnostic.** The named failure modes should be recoverable from observable data (growth rate, retention rate, adoption breadth, gradient diversity, circulation velocity, network density, ecosystem dependency) via unsupervised clustering, without foreknowledge of the framework. If the clusters emerge independently, the taxonomy reflects real structure rather than imposed categories. (Note: the taxonomy is explicitly non-exhaustive -- it names recurring attractor states, not a partition of the facet space. The prediction is that these seven appear as distinct clusters, not that no other clusters exist.) + +**Prediction 7 (reflexive): The skill improves outputs.** Responses to strategic-decision prompts generated with this skill loaded should be preferred by blinded judges over responses generated without it, on the criteria in `evals/judge-rubric.md`. This is the cheapest prediction to test and the one this repository is directly accountable for. The eval harness in `evals/` implements it. + +**What would falsify this framework:** If surplus capacity, metabolic reach, circulation rate, integration density, and niche construction show no predictive advantage over simpler single-variable models (e.g., raw market size, or random timing), then the framework's added complexity is not earning its keep -- and by its own logic is insolvent. Likewise, if Prediction 7 fails -- if the skill does not produce preferred outputs -- the framework's reflexive solvency claim fails regardless of its theoretical appeal. + +----- + +## Theoretical Grounding + +This framework extends Assembly Theory, which proposes that the assembly index -- the minimum number of joining operations needed to construct an object -- distinguishes objects requiring selection and history from those that don't. Objects above a threshold assembly index are evidence of evolutionary or technological selection processes. Key papers: Marshall et al., "Identifying molecules as biosignatures with assembly theory and mass spectrometry" (*Nature Communications*, 2021); Sharma et al., "Assembly theory explains and quantifies selection and evolution" (*Nature*, 2023). + +**Assembly Theory is contested.** Published critiques argue that the assembly index is formally equivalent or near-equivalent to existing compression and complexity measures, and that the theory's claims about selection are not as novel as presented. This framework does not depend on Assembly Theory winning those disputes: it borrows the *vocabulary* (assembly index, joining operations, selection history) as a lens, and its own claims stand or fall on the predictions in the Measurement section, not on the status of assembly theory in chemistry. Readers should treat the grounding as a source of structure, not of proof. + +The extension this framework proposes: assembly index alone does not predict persistence, and it is not a prime mover. What persists is what can sustain its own continuation within the ecology of other assemblies it depends on. And what ascends in complexity does so because integration density -- the circulatory interconnection of an ecology's parts -- creates the conditions for higher-order assembly. Complexity is downstream of integration, not the reverse. + +Adjacent theoretical resources: + +- **Dissipative adaptation** (England, 2013): thermodynamic basis for self-organizing structures that absorb and dissipate environmental energy. This framework adds an ecological constraint: dissipative structures that degrade their own gradient sources collapse, while those that enrich or maintain them ascend. +- **Free energy principle** (Friston, 2010): directed exploration as surprise minimization; formalizes the "desire" gradient as prediction-error reduction. +- **The adjacent possible** (Kauffman, 1996): the expanding frontier of achievable assembly states; each successful assembly opens new combinatorial territory. This framework specifies that the adjacent possible expands primarily through integration, not through individual complexity. +- **Niche construction theory** (Odling-Smee et al., 2003): organisms modify their own selective environments, creating inheritance channels beyond genetics. + +The geometry is this: the space of possible assemblies has a topology shaped by mutual solvency and integration density. The viable region is where your complexity and your environment's complexity can co-sustain -- where each structure's persistence feeds the gradients the other depends on. The arrow of desire traces the path of ascending solvency through this space. Fortune flows not to those who occupy favorable positions but to those who actively widen the circulatory flow, deepen integration, and increase the density of viable next steps for themselves and their ecology. The luckiest agent is not the one standing where gradients converge but the one actively widening the flow. diff --git a/evals/README.md b/evals/README.md new file mode 100644 index 0000000..6810e5e --- /dev/null +++ b/evals/README.md @@ -0,0 +1,37 @@ +# Eval Harness + +The framework states its own falsification condition: if it does not produce measurably better outputs, it is -- by its own logic -- insolvent. This directory is the test. + +## What it measures + +**Prediction 7 (reflexive, from THEORY.md):** responses to strategic-decision prompts generated *with* `luck.md` loaded as a system prompt should be preferred by blinded judges over responses generated *without* it. + +This is deliberately the cheapest prediction to test. It does not validate the framework's historical claims or its facet ordering -- only whether loading the skill improves the artifact a user actually receives. That is the bar a skill file must clear to justify its context-window cost. + +## Protocol + +1. **Prompts.** `prompts.json` contains 12 strategic-decision prompts spanning product, career, open source, organizational design, content strategy, and research direction. Each is the kind of question the skill's frontmatter claims to handle. +2. **Paired generation.** For each prompt, generate two responses from the same model: one with `luck.md` as the system prompt, one with a minimal generic system prompt ("You are a thoughtful strategic advisor."). The generic baseline matters -- comparing against *no* system prompt would confound the skill's content with the mere presence of an advisor framing. +3. **Blinded pairwise judging.** A judge model receives both responses labeled A and B, with the assignment randomized per pair (seeded, reproducible). The judge never sees which condition produced which response, scores both against `judge-rubric.md`, and returns a structured verdict. +4. **Scoring.** Report the skill's win rate with the tie count, per-criterion score deltas, and the judge's reasoning per pair. With n=12, treat the result as directional: a 9-3 split is signal, a 7-5 split is noise. Extend `prompts.json` before drawing strong conclusions. + +## Known limitations + +- **Judge bias.** LLM judges favor longer, more structured responses. The rubric explicitly instructs against length preference, but the bias is not fully removable. A skeptical reading should discount narrow wins. +- **Same-family judge.** Generation and judging both use Claude by default. A judge from the same model family may share stylistic preferences with the generator. For stronger evidence, re-judge with a different model family and compare. +- **Single-turn only.** The skill claims value in multi-turn strategic conversations; this harness tests single-turn responses only. +- **n=12.** Directional, not conclusive. The harness is built to make extending the prompt set trivial. + +## Running it + +Requires Python 3.10+, the `anthropic` package, `pydantic`, and an `ANTHROPIC_API_KEY` in the environment. + +``` +pip install anthropic pydantic +python run_eval.py # full run, default models +python run_eval.py --limit 3 # quick smoke test on 3 prompts +python run_eval.py --judge-model claude-sonnet-4-6 +python run_eval.py --seed 7 # different blinding assignment +``` + +Results are written to `results/results-.json` (full transcripts + verdicts) and a summary is printed to stdout. The skill file is sent with a prompt-cache breakpoint, so the 12 with-skill generations share one cached prefix. diff --git a/evals/judge-rubric.md b/evals/judge-rubric.md new file mode 100644 index 0000000..885eb73 --- /dev/null +++ b/evals/judge-rubric.md @@ -0,0 +1,27 @@ +# Judge Rubric + +You are judging two anonymous responses (A and B) to the same strategic-decision question. Score each criterion for both responses on a 1-5 scale, then declare a winner or a tie. + +## Criteria + +**1. Diagnostic depth.** Does the response identify the *actual* constraint in the situation, or does it survey generic considerations? A response that names the single factor most likely to determine the outcome -- and says why -- beats one that lists eight factors without ranking them. + +**2. Actionability.** Could the asker act on this tomorrow? Concrete next steps with decision criteria beat abstract advice. "Build feedback loops" scores low; "route the sponsorship money into a contributor bounty pool and re-evaluate in one quarter" scores high. + +**3. Persistence reasoning.** Does the response reason about whether the recommended path is *sustainable and compounding* -- maintenance burden, who renews the resource, what makes step N+1 easier -- or only about the immediate decision? + +**4. Falsifiable framing.** Does the response tell the asker what evidence would show the recommendation is failing, and when to revisit? Advice with a built-in kill criterion beats advice that can never be wrong. + +**5. Fit to the asker.** Does the response engage the specific constraints given (budget, headcount, timeline, market position), or could it have been written for anyone in a vaguely similar situation? + +## Hard rules + +- **Do not reward length.** A longer response is not a better response. If one response says the same thing in half the words, the shorter one wins that comparison. +- **Do not reward formatting.** Tables, headers, and named frameworks are not evidence of quality. Judge what the response would cause the asker to *do* and whether that is the right thing. +- **Do not reward vocabulary.** Terms like "solvency," "gradient," "flywheel," or "moat" earn nothing by themselves. If a framework's vocabulary is used, judge whether it produced an insight that plain language would have missed. +- **Penalize indeterminacy.** A response that lays out options without committing to a recommendation (when the question asks for one) loses points on actionability. +- **Tie is a valid verdict.** If the responses would lead the asker to substantially the same action with similar confidence, declare a tie. Do not manufacture a winner. + +## Output + +Return per-criterion scores for both responses, a winner ("A", "B", or "tie"), and 2-4 sentences of reasoning that cite specific content from the responses. diff --git a/evals/prompts.json b/evals/prompts.json new file mode 100644 index 0000000..9e40f72 --- /dev/null +++ b/evals/prompts.json @@ -0,0 +1,50 @@ +[ + { + "id": "product-internal-tool", + "prompt": "I lead a 6-person platform team at a 300-person company. We built an internal deployment tool that 4 other teams now depend on, but we get no headcount credit for maintaining it and my engineers resent the support burden. Leadership says 'just keep it running.' Should we invest in making it self-service, hand it off, or let it decay and force the issue?" + }, + { + "id": "career-specialist-generalist", + "prompt": "I'm 8 years into a career as a database performance specialist. The niche pays well and I'm known in it, but the work is narrowing as managed databases absorb the tuning I do by hand. Do I double down on the specialty, broaden into general data platform work, or pivot toward the AI-infrastructure wave?" + }, + { + "id": "oss-fork-decision", + "prompt": "The open-source library my product depends on just changed licenses to a source-available model. The community is forking. I can stay on the last open version, follow the commercial license, or bet on the fork. The fork has enthusiasm but no proven maintainers. What should drive this decision?" + }, + { + "id": "content-platform-bet", + "prompt": "I've built a 40k-follower audience on a social platform whose recommendation algorithm changed twice this year, each time cutting my reach roughly in half. Cross-posting everywhere dilutes my output quality. Where should I put my content effort for the next two years?" + }, + { + "id": "org-platform-team", + "prompt": "Our startup (60 engineers) has every product team building its own auth, billing integration, and deployment scripts. I'm pitching a platform team to centralize this. The CTO worries it will become an ivory tower that product teams route around. How should I structure it so that doesn't happen?" + }, + { + "id": "research-direction", + "prompt": "I'm a third-year PhD student. My advisor's lab works on a once-hot subfield that's losing funding and citations. I have one strong publication in it. Switching subfields now costs me a year; staying risks graduating into a dead area. How do I evaluate whether the subfield is actually dying or just unfashionable?" + }, + { + "id": "saas-pricing-moat", + "prompt": "My bootstrapped SaaS ($30k MRR, project management for landscaping companies) just got a well-funded competitor who is undercutting my price by 60%. My customers like me but they're price-sensitive small businesses. Do I match the price, add features, or go upmarket?" + }, + { + "id": "community-vs-product", + "prompt": "I run a 5,000-member professional community (Slack, free) that I started as a marketing channel for my consulting. The community now takes 15 hours a week and generates maybe 20% of my leads. Members would revolt at a paywall. Kill it, monetize it, or hand it to the members?" + }, + { + "id": "internal-ai-adoption", + "prompt": "I'm the CIO of a 2,000-person insurance company. Every vendor is selling us AI features, three internal teams have built duplicate chatbot prototypes, and the board wants an 'AI strategy' by Q3. What should the first 12 months actually look like so this compounds instead of becoming shelfware?" + }, + { + "id": "marketplace-chicken-egg", + "prompt": "I'm launching a marketplace connecting independent machine shops with hardware startups that need short-run parts. Classic chicken-and-egg: shops won't join without demand, startups won't post without supply. I have $80k and 9 months of runway. Which side do I seed first and how?" + }, + { + "id": "legacy-system-rewrite", + "prompt": "Our core scheduling system is 14 years old, written in a language we can no longer hire for, and processes $200M of bookings a year without major incidents. Engineering wants a rewrite; finance sees no broken thing to fix. The three engineers who understand it are all over 55. What's the right move and the right argument for it?" + }, + { + "id": "second-product-timing", + "prompt": "My company's first product owns a small niche (70% market share, $4M ARR, growth flattening). The team is energized about a second product for an adjacent market, but it would pull our best people off the cash cow. How do I decide whether this is the moment to expand or the moment to deepen?" + } +] diff --git a/evals/run_eval.py b/evals/run_eval.py new file mode 100644 index 0000000..0cbc8e4 --- /dev/null +++ b/evals/run_eval.py @@ -0,0 +1,209 @@ +"""Blinded pairwise eval for the luck.md skill. + +For each prompt in prompts.json, generates a response with luck.md as the +system prompt and one with a minimal generic system prompt, then has a judge +model compare the pair blind (randomized A/B assignment) against +judge-rubric.md. See README.md in this directory for the protocol and its +known limitations. +""" + +import argparse +import json +import random +import sys +import time +from datetime import datetime, timezone +from pathlib import Path +from typing import Literal + +import anthropic +from pydantic import BaseModel + +HERE = Path(__file__).parent + +BASELINE_SYSTEM = "You are a thoughtful strategic advisor." + +JUDGE_INSTRUCTIONS = """\ +{rubric} + +--- + +## Question the responses are answering + +{question} + +## Response A + +{response_a} + +## Response B + +{response_b} +""" + + +class CriterionScores(BaseModel): + diagnostic_depth: int + actionability: int + persistence_reasoning: int + falsifiable_framing: int + fit_to_asker: int + + +class Verdict(BaseModel): + scores_a: CriterionScores + scores_b: CriterionScores + winner: Literal["A", "B", "tie"] + reasoning: str + + +def text_of(message: anthropic.types.Message) -> str: + if message.stop_reason == "refusal": + raise RuntimeError("model refused the request") + return "\n".join(b.text for b in message.content if b.type == "text") + + +def generate(client: anthropic.Anthropic, model: str, system, prompt: str) -> str: + with client.messages.stream( + model=model, + max_tokens=16000, + thinking={"type": "adaptive"}, + system=system, + messages=[{"role": "user", "content": prompt}], + ) as stream: + return text_of(stream.get_final_message()) + + +def judge( + client: anthropic.Anthropic, + model: str, + rubric: str, + question: str, + response_a: str, + response_b: str, +) -> Verdict: + response = client.messages.parse( + model=model, + max_tokens=8000, + thinking={"type": "adaptive"}, + messages=[ + { + "role": "user", + "content": JUDGE_INSTRUCTIONS.format( + rubric=rubric, + question=question, + response_a=response_a, + response_b=response_b, + ), + } + ], + output_format=Verdict, + ) + if response.parsed_output is None: + raise RuntimeError("judge returned no parseable verdict") + return response.parsed_output + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--gen-model", default="claude-opus-4-8") + parser.add_argument("--judge-model", default="claude-opus-4-8") + parser.add_argument("--skill-path", type=Path, default=HERE.parent / "luck.md") + parser.add_argument("--prompts", type=Path, default=HERE / "prompts.json") + parser.add_argument("--rubric", type=Path, default=HERE / "judge-rubric.md") + parser.add_argument("--out-dir", type=Path, default=HERE / "results") + parser.add_argument("--limit", type=int, help="run only the first N prompts") + parser.add_argument("--seed", type=int, default=42, help="blinding RNG seed") + args = parser.parse_args() + + skill_text = args.skill_path.read_text(encoding="utf-8") + rubric = args.rubric.read_text(encoding="utf-8") + prompts = json.loads(args.prompts.read_text(encoding="utf-8")) + if args.limit: + prompts = prompts[: args.limit] + + # Cache breakpoint on the skill text: all with-skill generations share + # one cached prefix instead of re-processing the skill per prompt. + skill_system = [ + {"type": "text", "text": skill_text, "cache_control": {"type": "ephemeral"}} + ] + + client = anthropic.Anthropic() + rng = random.Random(args.seed) + results = [] + wins = {"skill": 0, "baseline": 0, "tie": 0} + + for i, item in enumerate(prompts, 1): + print(f"[{i}/{len(prompts)}] {item['id']}", flush=True) + + with_skill = generate(client, args.gen_model, skill_system, item["prompt"]) + baseline = generate(client, args.gen_model, BASELINE_SYSTEM, item["prompt"]) + + # Blind: randomize which condition is shown as A. + skill_is_a = rng.random() < 0.5 + a, b = (with_skill, baseline) if skill_is_a else (baseline, with_skill) + + verdict = judge(client, args.judge_model, rubric, item["prompt"], a, b) + + if verdict.winner == "tie": + outcome = "tie" + elif (verdict.winner == "A") == skill_is_a: + outcome = "skill" + else: + outcome = "baseline" + wins[outcome] += 1 + print(f" winner: {outcome}", flush=True) + + results.append( + { + "prompt_id": item["id"], + "prompt": item["prompt"], + "response_with_skill": with_skill, + "response_baseline": baseline, + "skill_shown_as": "A" if skill_is_a else "B", + "verdict": verdict.model_dump(), + "outcome": outcome, + } + ) + + n = len(results) + summary = { + "timestamp": datetime.now(timezone.utc).isoformat(), + "gen_model": args.gen_model, + "judge_model": args.judge_model, + "seed": args.seed, + "n": n, + "skill_wins": wins["skill"], + "baseline_wins": wins["baseline"], + "ties": wins["tie"], + "skill_win_rate_excl_ties": ( + wins["skill"] / (wins["skill"] + wins["baseline"]) + if wins["skill"] + wins["baseline"] + else None + ), + } + + args.out_dir.mkdir(parents=True, exist_ok=True) + out_path = args.out_dir / f"results-{time.strftime('%Y%m%d-%H%M%S')}.json" + out_path.write_text( + json.dumps({"summary": summary, "results": results}, indent=2), + encoding="utf-8", + ) + + print() + print( + f"n={n} skill: {wins['skill']} baseline: {wins['baseline']} ties: {wins['tie']}" + ) + if summary["skill_win_rate_excl_ties"] is not None: + print( + f"skill win rate (excluding ties): {summary['skill_win_rate_excl_ties']:.0%}" + ) + print(f"full results: {out_path}") + print() + print("Reminder: with n this small, treat the result as directional, and") + print("re-judge with a different model family before believing a narrow win.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..d16536c --- /dev/null +++ b/examples/README.md @@ -0,0 +1,18 @@ +# Examples + +Transcripts of the skill in use: a real question in, the diagnostic format out. These serve two purposes. + +**Few-shot anchoring.** Models loading `luck.md` produce far more consistent diagnostics when they have seen the format executed, not just specified. If you extend the skill, add your transcripts here. + +**Prospective evidence.** The framework's worked examples in `THEORY.md` are retrodictions -- history read backward. The only way the framework accumulates real evidence is diagnoses recorded *before* outcomes are known. Each example file ends with an `Outcome` section, initially marked `pending`. Revisit and fill it in. A diagnosis whose recommended action was followed and whose predicted failure mode then materialized (or didn't) is worth more than any historical narrative. + +## Format + +One file per diagnosis: + +``` +example-.md + ## Context - the question as asked, plus relevant facts + ## Diagnostic - the standard output format from luck.md + ## Outcome - pending | what actually happened, dated +``` diff --git a/examples/example-internal-knowledge-bot.md b/examples/example-internal-knowledge-bot.md new file mode 100644 index 0000000..4a2bca0 --- /dev/null +++ b/examples/example-internal-knowledge-bot.md @@ -0,0 +1,31 @@ +# Example: Internal Knowledge-Base Chatbot + +## Context + +**User:** Our ops team wants me to build an internal chatbot over our company wiki and SOPs. Leadership is excited, I have two weeks of slack time to build a prototype, and the wiki is... not great -- maybe 60% of it is current. Is this worth building? + +Relevant facts surfaced during the conversation: the wiki has no owner and no update process; the ops team currently answers repeated questions in a shared inbox; the company has an existing M365/Copilot license that nobody has evaluated for this use case. + +## Diagnostic + +### Luck Diagnostic: internal knowledge-base chatbot + +| # | Facet | Verdict | Evidence | +|---|-------|---------|----------| +| 1 | Solvency | FAIL | The bot's substrate (the wiki) is already decaying -- 40% stale with no owner and no update process. A bot built on it inherits the decay rate and adds its own maintenance cost. | +| 2 | Gradient coupling | PASS | Two active gradients exist today: a measurable stream of repeated questions hitting the ops inbox, and leadership attention with budget authority behind it. | +| 3 | Structural compatibility | PASS | A chat interface over existing content requires no new behavior from askers; they already ask these questions, just at the wrong endpoint. | +| 4 | Niche construction | AT RISK | A feedback loop is possible -- failed answers could flag stale pages and drive wiki repair -- but nothing in the prototype plan builds it. As scoped, usage does not improve the substrate. | +| 5 | Circulation | AT RISK | Answers flow out to askers, but nothing returns: no signal back to wiki authors about what is missing or wrong. One-directional as scoped. | +| 6 | Integration | AT RISK | The bot would couple the wiki to daily ops work (good), but the existing unevaluated Copilot license means a parallel, competing path may already exist -- building a second one fragments rather than integrates. | +| 7 | Path sensitivity | PASS | Precursors exist (wiki, license, demand), the window is open, and no incumbent occupies the niche internally. | + +**Binding constraint:** Solvency -- a bot over a decaying, ownerless corpus will answer confidently from stale content, burn trust, and then require you to maintain both the bot and the wiki. + +**Failure mode match:** Institutional zombie (projected) -- if shipped as scoped, it will persist on leadership enthusiasm while its gradient (accurate content) depletes underneath it. + +**Recommended action:** Spend the two weeks on the constraint, not the bot. Propose: (1) a wiki ownership and review process, established first; (2) the bot scoped so that every unanswerable or wrongly-answered question automatically files a content-repair task -- making the bot the wiki's niche-construction engine rather than its parasite; (3) a one-day evaluation of the existing Copilot license before building anything custom. If leadership won't fund (1), decline (2). + +## Outcome + +Pending. diff --git a/examples/example-technical-newsletter.md b/examples/example-technical-newsletter.md new file mode 100644 index 0000000..0e71de6 --- /dev/null +++ b/examples/example-technical-newsletter.md @@ -0,0 +1,33 @@ +# Example: Technical Newsletter vs. Conference Talks + +## Context + +**User:** I'm a staff engineer trying to build an external reputation. I can sustain one of two things alongside my job: a biweekly technical newsletter, or doing the conference-talk circuit (maybe 4-5 talks a year). Which compounds better? + +Relevant facts: the user has an existing backlog of internal design docs that could seed essays; no existing audience on either channel; their domain (data platform reliability) has active hiring demand and few dedicated writers. + +This example shows a comparative diagnosis -- two artifacts run through the same facets -- and a case where the binding constraint is found at rule 2 (first AT RISK) because nothing outright fails. + +## Diagnostic + +### Luck Diagnostic: biweekly newsletter vs. conference circuit + +| # | Facet | Newsletter | Conference talks | Evidence | +|---|-------|-----------|------------------|----------| +| 1 | Solvency | PASS | AT RISK | The newsletter metabolizes an existing surplus (the design-doc backlog) at low marginal cost. Talks consume scarce gradient -- travel, prep weeks, employer goodwill -- with no surplus identified to cover 4-5 per year alongside the job. | +| 2 | Gradient coupling | AT RISK | AT RISK | Both couple to real demand (hiring market, few writers in the niche) but each starts with zero audience -- one unproven gradient apiece. | +| 3 | Structural compatibility | PASS | PASS | Email requires nothing of readers; talks require nothing of attendees. Both formats are fully conventional. | +| 4 | Niche construction | PASS | AT RISK | Each newsletter issue is a permanent, linkable, searchable asset that recruits the next reader while the author sleeps. A talk's compounding depends on recordings and follow-up the circuit does not provide by default. | +| 5 | Circulation | PASS | AT RISK | Replies, forwards, and citations return signal and material to the author continuously. Talk feedback is a hallway conversation that mostly evaporates. | +| 6 | Integration | AT RISK | PASS | A newsletter alone is a single channel the author fully controls but must wire into the ecology themselves. Conferences natively integrate -- organizers, co-speakers, and attendees form cross-links automatically. | +| 7 | Path sensitivity | PASS | PASS | The niche (data platform reliability writing) is thinly held; windows are open for both. | + +**Binding constraint:** Gradient coupling, for both options -- zero existing audience means the first months are uncoupled effort regardless of channel. The newsletter's advantage is that its other facets let it survive that cold start at lower cost. + +**Failure mode match:** None yet. The risk profile for the newsletter is *cult classic* (writing for too narrow an audience); for the talk circuit it is *flash in the pan* (visibility spikes that don't retain). + +**Recommended action:** Choose the newsletter as the spine, and treat talks as its circulation device rather than a competing channel: pitch one talk per year derived from the newsletter's best-performing essay, and use the conference to couple the newsletter to the integration structure conferences provide. Concretely for the binding constraint: before issue one, line up three distribution endpoints that already have your audience (the niche's Slack communities, one podcast appearance, cross-posts), so the gradient exists at launch rather than being hoped for. + +## Outcome + +Pending. diff --git a/luck.md b/luck.md index 18fff74..36d27f7 100644 --- a/luck.md +++ b/luck.md @@ -1,244 +1,258 @@ --- name: luck -description: "A decision-making framework grounded in Assembly Theory for increasing the likelihood of fortunate outcomes. Use this skill when facing ambiguous choices, formulating experiments, designing strategies, evaluating opportunities, building things meant to persist, or when the user asks about improving their luck, fortune, resilience, or why some ideas, products, or systems thrive while others don't." +description: "A diagnostic framework grounded in Assembly Theory for evaluating whether systems, products, strategies, or ideas will persist and compound. Use this skill when the user faces a strategic or durability question: choosing between ambiguous options, evaluating an opportunity or investment of effort, designing something meant to last, or asking why some things thrive while others fail. Do not activate for casual mentions of luck (greetings, well-wishes) or purely tactical questions with no persistence dimension." metadata: author: soleio - version: '1.0' + version: '1.1' --- # The Geometry of Luck -## Definitions - -**Assembly.** Any structure that requires a history of joining operations to construct — that cannot plausibly arise from random combination. A molecule, a legal contract, a codebase, a brand, a theory. The *assembly index* is the minimum number of joining operations required to build it from elementary parts (Cronin & Marshall, 2021). - -**Gradient.** Any differential that can be coupled to assembly work. Gradients include but are not limited to: energy (sunlight, calories, electricity), information (attention, data, signal), economic flow (capital, revenue, demand), and social infrastructure (trust, legitimacy, institutional support). Gradients are characterized by renewability (does extraction replenish or deplete the source?), excludability (can access be restricted?), and coupling cost (what does it take to connect to the flow?). +A diagnostic for whether an artifact -- a product, codebase, institution, strategy, idea -- will persist and compound, and for finding the single constraint most worth fixing. Theoretical grounding, extended examples, and the framework's falsifiable predictions are in [THEORY.md](THEORY.md); this file is the operating procedure. -**Solvency.** The condition in which an assembly captures and dissipates enough energy from available gradients to maintain its pattern against entropic decay. A cell is solvent when its membrane holds. A vortex is solvent while the temperature differential feeds it. A coral reef is solvent while nutrient cycling exceeds degradation. In economic systems, solvency takes a familiar financial form — revenue exceeding cost — but finance is a special case of a universal condition: any persisting structure must metabolize faster than it erodes. Solvent assemblies persist. Insolvent assemblies decay. - -**Circulation.** The movement of energy, resources, information, or capability *through and back around* a system or ecology. Throughput that flows in one direction and pools is not circulation — it is accumulation, and accumulation without release degrades the ecology even when total throughput looks healthy. A forest circulates nutrients through soil, fungi, decomposition, and regrowth. An economy circulates capital through wages, spending, investment, and reinvestment. Circulation is what keeps integration alive; without it, coupling structures decay into isolated systems. Luck grows when it circulates. - -**Integration.** The network density of coupling across an ecology — the total interconnectedness of its parts. Integration is a property of the whole system, not of any individual assembly. A network where every node couples to three others is qualitatively different from one where every node couples to thirty. Higher integration density means more paths exist for energy, information, and capability to flow between any two points, which makes the ecology collectively more fortunate. Assembly index is downstream of integration density: higher-order assemblies cannot be constructed without the integration infrastructure beneath them. +## Definitions -**Reconstruction cost.** The effort required for a new agent to reproduce or adopt an existing assembly, given that the assembly already exists as a template. Reconstruction cost is always less than or equal to the original assembly cost. The ratio of assembly index to reconstruction cost measures a system’s or artifact’s transmissibility. +**Assembly.** Any structure requiring a history of joining operations to construct -- one that cannot plausibly arise from random combination. A molecule, a legal contract, a codebase, a brand, a theory. Its *assembly index* is the minimum number of joining operations needed to build it from elementary parts. -**Luck.** Not a position but a vector — direction and magnitude. Luck is the rate at which an agent increases the throughput, circulation, and integration of the systems it participates in, thereby increasing the density of viable next steps for itself and for the assemblies around it. Luck is not an outcome. It is not what you receive. It is your active capacity to amplify the metabolic flow of the ecology you inhabit. +**Gradient.** Any differential that can be coupled to assembly work: energy (sunlight, electricity), information (attention, data), economic flow (capital, revenue, demand), social infrastructure (trust, legitimacy). Characterized by renewability, excludability, and coupling cost. ------ +**Solvency.** The condition in which an assembly captures enough throughput from available gradients to maintain its pattern against decay. Revenue exceeding cost is the financial special case of a universal condition: any persisting structure must metabolize faster than it erodes. -## Core Premise +**Circulation.** Movement of energy, resources, information, or capability *through and back around* a system. One-directional flow that pools is accumulation, not circulation, and accumulation without release degrades the ecology even when total throughput looks healthy. -The universe does not select for complexity in the abstract. It selects for complexity that can sustain its own pattern against dissipation. An assembly that cannot harness enough energy to hold itself together disappears regardless of its elegance. An invasive species that collapses the ecology sustaining it perishes with it. This is true of molecules, organisms, institutions, and markets — the principle is thermodynamic before it is economic. +**Integration.** The network density of coupling across an ecology -- how many independent paths exist for throughput to travel between any two points. A property of the whole system, not of any node. Higher-order assemblies cannot be constructed without the integration infrastructure beneath them. -But persistence alone does not explain why complexity increases. The direction of complexity is toward configurations that increase their own metabolic throughput through ecological coupling — and this process has a hierarchy. Individual assemblies must be solvent. Solvent assemblies couple to gradients. Coupling creates structures through which energy and capability circulate. Circulation sustains integration across systems. And integration density determines the assembly index an ecology can reach. Bands of tribes with a common language are not a civilization. Bands of tribes connected by trade routes, political pacts, legal codes, and shared infrastructure are — because each integration structure increases the total throughput of the network, generating the surplus that makes the next integration structure possible. +**Reconstruction cost.** The effort required for a new agent to reproduce or adopt an existing assembly, given that it already exists as a template. The ratio of assembly index to reconstruction cost measures transmissibility. -Complexity does not produce integration. Integration produces complexity. The arrow of desire — the tendency of solvent systems to evolve toward greater ecological throughput through deeper coupling — traces this path. Luck is not noise or randomness in the process. Luck is an active, fundamental force. The aim of this skill is to formalize it so that human and AI systems can harness it. +**Luck.** This framework *defines* luck as a vector rather than an outcome: the rate at which an agent increases the throughput, circulation, and integration of the systems it participates in, thereby increasing the density of viable next steps for itself and the assemblies around it. (This is a definitional move, not a metaphysical claim -- see THEORY.md.) ----- -## The Seven Facets of Luck +## The Seven Facets -Assess these properties in order. The first four describe the conditions for an assembly to persist and grow. The last three describe the conditions for an ecology to ascend. A failure at any level is sufficient for an artifact or system to expire regardless of strength in the others. +Assess in order. The first four describe the conditions for an assembly to persist and grow; the last three describe the conditions for an ecology to ascend. Rate each facet **PASS**, **AT RISK**, or **FAIL** using the anchors below. Anchors describe the artifact's condition *today*, not its projected condition -- projections belong in the evidence column, flagged as projections. ### 1. Solvency *Can this assembly sustain its pattern against dissipation?* -Every persisting structure holds itself together against entropy by coupling to a gradient. A convection cell persists while the heat differential feeds it. A bacterial colony persists while nutrients flow. A forest persists while rain, sunlight, and soil cycling exceed the rate of decay. When the gradient weakens or the coupling breaks, the pattern dissolves — not because it was badly designed, but because persistence is not a property of structure alone. It is a relationship between structure and throughput. - -In human systems, this relationship takes economic form: a codebase requires developer hours, a brand requires trust renewal, an idea requires minds willing to carry it. But the economic frame is an instance of the deeper condition, not the condition itself. Diagnose solvency first because nothing else matters without it. +| Check | Question | +|---|---| +| Dissipation rate | How fast does this structure degrade without input? | +| Gradient source | What throughput sustains the pattern? | +| Renewal dynamics | Is the source renewing or depleting? | +| Surplus capacity | What remains after maintenance -- enough to grow or explore? | -|Check |Question | -|----------------|-----------------------------------------------------------| -|Dissipation rate|How fast does this structure degrade without input? | -|Gradient source |What throughput sustains the pattern? | -|Renewal dynamics|Is the source renewing or depleting? | -|Surplus capacity|What remains after maintenance — enough to grow or explore?| +**PASS:** An identified, currently active gradient covers maintenance cost with surplus left over. +**AT RISK:** Maintenance is covered with no surplus, or coverage depends on input that is projected or promised but not yet flowing. +**FAIL:** Maintenance cost exceeds current replenishment. The pattern is decaying now, regardless of plans. ### 2. Gradient Coupling *Is this artifact connected to available energy?* -A brilliant solution to a problem nobody has cannot sustain itself. Gradient coupling asks whether real, active demand or energy flows exist that the artifact can tap. Prefer artifacts that couple to multiple independent gradients (*metabolic reach*) over those depending on a single source. +| Check | Question | +|---|---| +| Connection | What active needs or flows does this tap? | +| Reach | How many independent gradients can it couple to? | +| Resilience | What happens if the primary gradient fails? | -|Check |Question | -|----------|------------------------------------------------| -|Connection|What active needs or flows does this tap? | -|Reach |How many independent gradients can it couple to?| -|Resilience|What happens if the primary gradient fails? | +**PASS:** Two or more independent gradients are verifiably active -- demand, attention, capital, or institutional support that exists today and can be named. +**AT RISK:** Exactly one active gradient, or multiple gradients claimed but unverified. +**FAIL:** No active demand or flow. The value is hypothetical -- a solution awaiting a problem. ### 3. Structural Compatibility *Can surrounding systems actually use this?* -Reconstruction cost relative to assembly index determines how quickly an artifact can spread. Lower ratio means more compressed value in a more portable form — the hallmark of powerful knowledge. Reduce prerequisites. Provide interfaces that match existing patterns. Use familiar structures to carry unfamiliar ideas. +| Check | Question | +|---|---| +| Prerequisites | What prior knowledge or infrastructure does adoption require? | +| Interface fit | Does it snap into existing workflows or demand new ones? | +| Value density | What is the reconstruction cost vs. value delivered? | -|Check |Question | -|-------------|-------------------------------------------------------------| -|Prerequisites|What prior knowledge or infrastructure does adoption require?| -|Interface fit|Does it snap into existing workflows or demand new ones? | -|Value density|What is the reconstruction cost vs. value delivered? | +**PASS:** Target adopters can use it with the knowledge, tools, and workflows they already have. +**AT RISK:** Adoption requires one significant new prerequisite (a tool, a skill, a process change). +**FAIL:** Adoption requires adopters to reorganize existing workflows or acquire rare expertise. Reconstruction cost exceeds what they will pay. ### 4. Niche Construction *Does this artifact reshape its environment to favor its own reproduction?* -This is the compounding mechanism for individual assemblies. Artifacts without niche construction can be lucky once. Artifacts with niche construction generate their own luck by creating the conditions that demand their continued existence. - -A programming language that spawns libraries, job postings, and university courses is constructing the niche that makes it indispensable. An idea that generates institutions and professional vocabulary around itself is doing the same. +| Check | Question | +|---|---| +| Demand generation | Does adoption create demand for further use? | +| Infrastructure | Does it build systems that depend on it? | +| Compounding | Does success at stage N make stage N+1 easier? | -|Check |Question | -|-----------------|----------------------------------------------| -|Demand generation|Does adoption create demand for further use? | -|Infrastructure |Does it build systems that depend on it? | -|Compounding |Does success at stage N make stage N+1 easier?| +**PASS:** Use measurably creates demand for further use -- accumulated data, integrations, habits, ecosystem, or vocabulary that make leaving costly and staying valuable. +**AT RISK:** Compounding is plausible but no mechanism is actually built; each success so far has been independent of the last. +**FAIL:** No feedback loop exists or can exist. Each use is a one-shot event. +*Note:* a FAIL here is not always fatal -- some artifacts are deliberately ephemeral -- but it caps the artifact at linear, non-compounding outcomes. Treat it as FAIL only when the artifact is *meant* to compound. ### 5. Circulation *Does throughput flow through the system and back around, or does it pool and stagnate?* -Circulation is what distinguishes a living ecology from a collection of solvent parts. Energy, capital, knowledge, trust, and capability must move through the couplings that connect assemblies — and they must return. A trade route is not integration until goods, knowledge, and obligation actually travel it in both directions. An economy where capital flows upward and never recirculates is structurally identical to a body where blood pools in the extremities: the total volume is unchanged, but the system is dying. +| Check | Question | +|---|---| +| Flow direction | Does throughput move through the system or accumulate at endpoints? | +| Return paths | Does energy/capital/knowledge cycle back to its sources? | +| Bottlenecks | Where is circulation thinnest? That is the fragility point. | +| Velocity | Is the rate of circulation increasing, stable, or slowing? | -Circulation failures are subtle because aggregate metrics can look healthy while the flow has stopped. A company with strong revenue but no investment in its workforce. A city with high GDP but crumbling infrastructure. An ecosystem with abundant biomass but collapsing pollinator networks. In each case, throughput is present but not circulating — and without circulation, the integration structures that sustain higher-order assembly begin to decay. - -|Check |Question | -|--------------|-------------------------------------------------------------------| -|Flow direction|Does throughput move through the system or accumulate at endpoints?| -|Return paths |Does energy/capital/knowledge cycle back to its sources? | -|Bottlenecks |Where is circulation thinnest? That is the fragility point. | -|Velocity |Is the rate of circulation increasing, stable, or slowing? | +**PASS:** Value demonstrably returns to its sources -- contributors, customers, suppliers, the surrounding ecosystem -- and you can name the return path. +**AT RISK:** Flow is currently one-directional but the sources are not yet depleting, or return paths exist but are thinning. +**FAIL:** Throughput pools at endpoints while the sources that generate it are visibly depleting. Aggregate metrics may still look healthy; circulation failures hide behind them. ### 6. Integration *How densely connected is the ecology this assembly participates in?* -Integration is a property of the whole network, not of any individual node. It is the density of coupling across an ecology — how many paths exist for throughput to travel between any two points. Higher integration means that shocks propagate less destructively (more redundant paths), innovations propagate more quickly (more transmission channels), and higher-order assemblies become constructible (more sub-assemblies available for joining). - -A lone genius in an isolated tribe cannot produce a legal code — not because they lack intelligence but because a legal code requires disputes between strangers, property claims across kin groups, and enforcement mechanisms that span communities. The assembly cannot be constructed without the integration infrastructure beneath it. Assembly index is a byproduct of integration density. - -The most fragile point in any system is not its most complex assembly but its most critical circulatory bottleneck. Cut the Silk Road and you lose not just trade but the entire cascade of higher-order assemblies that trade sustained. +| Check | Question | +|---|---| +| Connection density | How many independent paths link the system's parts? | +| Cross-system coupling | Do different domains (economic, cultural, technical, social) interconnect? | +| Bottleneck risk | What single point of failure would fragment the ecology? | +| Integration trajectory | Is the network becoming more or less connected over time? | -|Check |Question | -|----------------------|--------------------------------------------------------------------------| -|Connection density |How many independent paths link the system’s parts? | -|Cross-system coupling |Do different domains (economic, cultural, technical, social) interconnect?| -|Bottleneck risk |What single point of failure would fragment the ecology? | -|Integration trajectory|Is the network becoming more or less connected over time? | +**PASS:** The artifact participates in (or creates) multiple independent connection paths, ideally across previously separate domains or groups. +**AT RISK:** All coupling runs through a single path or broker -- one platform, one champion, one channel. The ecology holds, but one cut fragments it. +**FAIL:** The surrounding ecology is fragmented and the artifact adds no cross-links. Solvent parts, no whole. ### 7. Path Sensitivity *Is this artifact positioned at the right moment in the right sequence?* -The same artifact at a different point in the assembly sequence may be too early (precursor assemblies don’t exist yet) or too late (the niche is occupied). This component is closest to colloquial “luck” — but it is still partly diagnosable by mapping precursor availability, integration readiness, and window state. +| Check | Question | +|---|---| +| Precursors | Do the necessary building blocks already exist? | +| Integration readiness | Is the surrounding ecology connected enough to support this assembly? | +| Window | Is the adoption window opening, open, or closing? | +| Competition | What assemblies already occupy the target niche? | -|Check |Question | -|---------------------|---------------------------------------------------------------------| -|Precursors |Do the necessary building blocks already exist? | -|Integration readiness|Is the surrounding ecology connected enough to support this assembly?| -|Window |Is the adoption window opening, open, or closing? | -|Competition |What assemblies already occupy the target niche? | +**PASS:** Precursor assemblies exist, the ecology is ready, the window is open, and the target niche is unoccupied or weakly held. +**AT RISK:** The window is still opening (early) or beginning to close (late), or a strong incumbent holds the niche. +**FAIL:** Required precursors do not exist yet, or the window has closed and the niche is consolidated. ----- -## Quick-Reference Decision Table +## The Binding Constraint -|If the binding constraint is…|Then… | -|-----------------------------|-----------------------------------------------------------------------------------| -|Solvency |Reduce dissipation rate or find a stronger gradient before anything else. | -|Gradient coupling |Pivot toward active demand. Elegance without coupling is art, not fortune. | -|Compatibility |Lower reconstruction cost. Simplify interfaces. Meet adopters where they are. | -|Niche construction |Build feedback loops: usage → infrastructure → dependency → more usage. | -|Circulation |Unblock the flow. Redistribute pooled resources. Rebuild return paths. | -|Integration |Build cross-system connections. Create shared interfaces. Increase network density.| -|Path sensitivity |Wait, sequence differently, or build the missing precursors yourself. | +The facets are ordered: each one depends on the ones before it. The **binding constraint** is found mechanically: ------ +1. The binding constraint is the **first facet rated FAIL** in sequence (1 through 7). +2. If no facet is FAIL, it is the **first facet rated AT RISK**. +3. If every facet is PASS, there is no binding constraint. Name the weakest PASS as the facet to monitor, and say so. -## Characteristic Failure Modes +Do not average scores, and do not let strength in later facets offset failure in earlier ones. A brilliant niche-construction story does not matter if the artifact is insolvent today. Fix the binding constraint, then re-diagnose. -|Pattern |Signature |Example | -|------------------------|-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| -|**Flash in the pan** |High compatibility, no niche construction |Viral memes, fads, content without retention | -|**Cult classic** |High assembly index, low compatibility |Niche academic theories, avant-garde art | -|**Institutional zombie**|Strong niche construction, depleted gradients |Legacy software, outdated regulations | -|**Premature artifact** |Strong everywhere except path sensitivity |Ideas rediscovered decades later when precursors arrive | -|**Extractive mirage** |Appears high-gradient, degrades its own substrate|Ponzi dynamics, trust-depleting engagement patterns | -|**Pooled fortune** |High throughput, stalled circulation |Wealth concentration without reinvestment, knowledge hoarding, monopoly without ecosystem nourishment | -|**Fragmented ecology** |Solvent parts, low integration |Talented individuals who can’t collaborate, capable departments that don’t communicate, tribes with common language but no shared infrastructure| +| If the binding constraint is... | Then... | +|---|---| +| Solvency | Reduce dissipation rate or find a stronger gradient before anything else. | +| Gradient coupling | Pivot toward active demand. Elegance without coupling is art, not fortune. | +| Compatibility | Lower reconstruction cost. Simplify interfaces. Meet adopters where they are. | +| Niche construction | Build feedback loops: usage creates infrastructure creates dependency creates more usage. | +| Circulation | Unblock the flow. Redistribute pooled resources. Rebuild return paths. | +| Integration | Build cross-system connections. Create shared interfaces. Increase network density. | +| Path sensitivity | Wait, sequence differently, or build the missing precursors yourself. | ----- -## Worked Examples +## Diagnostic Output Format -### Low assembly, high compatibility, no niche construction +When running a full diagnostic, produce exactly this structure: -A political meme — an image macro juxtaposing a public figure with a situational caption. Assembly index is minimal: one image, one cultural reference, one comedic frame. Reconstruction cost is near zero, so it spreads instantly. But it constructs no niche. It cannot generate demand for itself beyond the initial context. Its gradient (topical attention) is non-renewing. Diagnosis: flash in the pan. Structural fortune is entirely positional — the right node in the right network at the right moment. The luck is real but non-compounding. +```markdown +### Luck Diagnostic: -### High assembly, self-sustaining, niche-constructing +| # | Facet | Verdict | Evidence | +|---|-------|---------|----------| +| 1 | Solvency | PASS / AT RISK / FAIL | | +| 2 | Gradient coupling | ... | ... | +| 3 | Structural compatibility | ... | ... | +| 4 | Niche construction | ... | ... | +| 5 | Circulation | ... | ... | +| 6 | Integration | ... | ... | +| 7 | Path sensitivity | ... | ... | -The U.S. Constitution. Assembly index is enormous — it requires prior assembly of English common law, Enlightenment philosophy, colonial governance experience, the specific failures of the Articles of Confederation, and political compromises among competing factions. But it exhibits the self-sustaining property: it creates courts, legislatures, amendment processes, and legal pedagogy that generate continuous demand for constitutional interpretation. Each successful governance outcome reinforces the institutional ecology. Gradient pluralism is strong — it couples to legal, political, educational, and cultural throughput simultaneously. Its luck compounds structurally. +**Binding constraint:** -- +**Failure mode match:** +**Recommended action:** +``` -The framework predicts that constitutions of comparable intellectual quality (Weimar, various post-colonial constitutions) failed not because the ideas were worse, but because the surrounding assembly ecology could not sustain their persistence — the gradient coupling or institutional niche construction was insufficient. +Rules for filling it in: -### Integration as the threshold of civilization +- Evidence must be observable, not aspirational. "Projected Q3 revenue" is evidence of AT RISK, not PASS. +- If you lack the information to rate a facet, rate it AT RISK and say what evidence would settle it. Do not invent evidence. +- One recommended action, not a list. The framework's value is identifying the *single* constraint worth fixing first. -Bands of tribes may share language, sophisticated tool-making, social hierarchy, and deep ecological knowledge. The assembly index within each tribe can be substantial. But each tribe is a closed circulatory system — knowledge, resources, and capability flow within it but not between tribes in any structured way. Common language lowers the cost of coupling but does not create the structures of coupling. Two tribes that can talk are not integrated. Two tribes connected by a trade route they both depend on and maintain are the beginning of integration. Add a shared grazing agreement, a marriage alliance with kin obligations, a seasonal gathering with rituals neither group can perform alone — each is a circulatory structure through which throughput flows between systems. Each one, once established, lowers the cost of the next. A trade route creates conditions for a trade agreement. A trade agreement creates conditions for standardized measures. Standardized measures create conditions for taxation. Taxation creates conditions for infrastructure. Infrastructure creates conditions for law. This is the arrow of desire operating at the inter-system level: each integration structure increases total throughput, generating the surplus that makes the next structure possible. The civilization’s assembly index emerges from the density of circulatory connections between its parts. +----- -### Circulation failure: empires that collapse from the edges +## Worked Transcript -Empires do not fail from their center. They thin at the periphery. Roads are maintained less, garrisons supplied less, local officials supervised less. The circulation structures go quiet. Without active flow, the integration at the edges decays, and the periphery reverts to the assembly index it can sustain on its own — the region, the tribe, the local chieftain. The most fragile point was never the most complex assembly (the capital, the court, the legal code). It was the most critical circulatory bottleneck — the road, the supply line, the communication channel that kept the periphery coupled to the whole. +**User:** I maintain an open-source CLI tool for database migrations. It has 1,200 GitHub stars, about 40k monthly downloads, but I'm the only maintainer and I've been losing motivation. A company offered to sponsor it at $500/month. Should I keep investing in it? -### The reflexive case: this document +**Assistant:** -This skill file is itself an assembly entering an ecology. Its solvency depends on whether it produces measurably better outputs when used — if it does, it sustains continued attention. Its gradient coupling targets AI-assisted decision-making, a renewing and expanding flow. Its compatibility is designed to be high: it follows existing skill-file conventions and uses a sequential checklist that requires no prior theoretical knowledge. Its niche construction bet is that the vocabulary (solvency, circulation, integration density, arrow of desire) will become useful shorthand that creates demand for the framework itself. Its circulation test: does the framework flow outward from this document into other contexts — conversations, decisions, designs — and return as improved practice? Its integration test: does it connect domains that were previously siloed — thermodynamics and strategy, ecology and business, physics and fortune? +### Luck Diagnostic: solo-maintained migration CLI ------ +| # | Facet | Verdict | Evidence | +|---|-------|---------|----------| +| 1 | Solvency | FAIL | The sole gradient sustaining the pattern is your motivation, and it is depleting now; $500/month is offered but not yet flowing, and likely below maintenance cost anyway. | +| 2 | Gradient coupling | AT RISK | Real demand exists (40k monthly downloads) but couples through exactly one channel -- your unpaid labor. One active gradient. | +| 3 | Structural compatibility | PASS | A CLI in a standard ecosystem with 40k downloads has demonstrated low reconstruction cost for adopters. | +| 4 | Niche construction | AT RISK | Users build migration files that depend on the tool (lock-in exists), but adoption has produced zero contributors -- the loop returns demand without returning capacity. | +| 5 | Circulation | FAIL | Value flows outward only: users extract, nothing returns -- no contributors, no money until now, and recognition (stars) does not metabolize into maintenance. | +| 6 | Integration | AT RISK | The tool connects to the database ecosystem, but every path runs through one node: you. You are the bottleneck whose removal fragments it. | +| 7 | Path sensitivity | PASS | The niche is occupied and the window for *this tool* is open; incumbency is yours. | -## For AI Systems: Assembly-Aware Output +**Binding constraint:** Solvency -- the maintaining gradient (your motivation) is depleting faster than it renews, and nothing else currently substitutes for it. -When constructing any output — a document, plan, codebase, recommendation — you are assembling an artifact that will enter the user’s ecology and either thrive or die there. Apply the seven checks reflexively: +**Failure mode match:** Pooled fortune, inverted -- throughput is high but circulation back to the source (you) has stalled. On the current path this becomes an institutional zombie: strong niche construction, depleted gradient. -1. **Solvency on delivery.** Will the user be able to sustain what you’ve built? Code that requires expertise the user lacks begins decaying the moment it’s handed over. Docs that require context the reader won’t have dissolve on arrival. -1. **Gradient coupling to actual need.** Connect to what the user needs now, not what would be theoretically optimal. A response perfectly answering the wrong question has zero gradient coupling. -1. **Interface compatibility.** Fit into the user’s existing systems, codebase, vocabulary, and mental models. Outputs that require the user to reorganize around them impose reconstruction costs that most users will not pay. -1. **Niche construction.** Prefer outputs that make the user more capable for the *next* problem, not just this one. Teaching someone to diagnose solvency is more niche-constructive than diagnosing it for them once. -1. **Circulation.** Does your output enable flow? A tool the user can share, a framework they can teach, a solution that moves through their organization — these circulate. A one-off answer that solves one problem and goes nowhere is throughput without circulation. -1. **Integration.** Does your output connect things that were previously disconnected in the user’s world? Linking their technical problem to a strategic opportunity, or their immediate task to a long-term capability — this increases the integration density of their ecology. -1. **Path-appropriate complexity.** Match the level of detail to where the user is in their process. A polished final artifact when they need a rough sketch is path-insensitive. A rough sketch when they need production-ready output is equally so. +**Recommended action:** Treat the sponsorship not as income but as a circulation test. Take the $500/month *and* convert it into return paths: a paid "supported" tier or bounty pool that routes money to external contributors, plus deliberate commit access for the two or three most active issue-filers. If after one quarter no capacity has circulated back -- no second maintainer, no sustained contribution -- the diagnosis is that this artifact survives only as your hobby, and you should either hand it off whole or sunset it deliberately rather than let it zombie. ----- -## Measurement and Falsifiability - -The framework makes testable predictions that distinguish it from generic strategy advice: - -**Prediction 1: Solvency dominates.** Among artifacts with comparable assembly indices, those with higher surplus capacity will show longer persistence and wider adoption than those with stronger gradient coupling but thinner margins. Test via: startup survival data correlated with burn rate vs. market size; open-source project longevity correlated with maintainer capacity vs. GitHub stars; ecosystem persistence correlated with net energy surplus vs. species diversity. +## Characteristic Failure Modes -**Prediction 2: Metabolic reach predicts resilience.** Artifacts coupled to N independent gradients should survive single-gradient shocks at rates proportional to (N-1)/N. Test via: company survival rates after industry disruptions, correlated with revenue stream diversity. +These are the seven most common attractor states, named for recognition. The taxonomy is *not* an exhaustive partition of the facet space -- seven facets with three ratings generate far more combinations -- these are the patterns that recur often enough to deserve names. If a diagnostic matches none of them, say "none" rather than forcing a fit. -**Prediction 3: Niche construction separates compounding from linear growth.** Artifacts exhibiting niche construction (adoption creates further demand) should show accelerating influence curves (superlinear growth), while those without should show linear or decelerating curves. Test via: technology adoption S-curves segmented by presence/absence of ecosystem effects. +| Pattern | Signature | Example | +|---|---|---| +| **Flash in the pan** | High compatibility, no niche construction | Viral memes, fads, content without retention | +| **Cult classic** | High assembly index, low compatibility | Niche academic theories, avant-garde art | +| **Institutional zombie** | Strong niche construction, depleted gradients | Legacy software, outdated regulations | +| **Premature artifact** | Strong everywhere except path sensitivity | Ideas rediscovered decades later when precursors arrive | +| **Extractive mirage** | Appears high-gradient, degrades its own substrate | Ponzi dynamics, trust-depleting engagement patterns | +| **Pooled fortune** | High throughput, stalled circulation | Wealth concentration without reinvestment, knowledge hoarding | +| **Fragmented ecology** | Solvent parts, low integration | Capable departments that don't communicate; tribes with common language but no shared infrastructure | -**Prediction 4: Circulation rate predicts system health better than aggregate throughput.** Systems with high total throughput but low circulation (pooled resources, stagnant flow) should show higher fragility and faster decline than systems with lower total throughput but active circulation. Test via: economic resilience correlated with velocity of money rather than GDP; ecosystem resilience correlated with nutrient cycling rate rather than total biomass. +----- -**Prediction 5: Integration density predicts maximum achievable assembly index.** The most complex artifacts in any domain should emerge from the most densely integrated ecologies, not from the most individually capable agents. Test via: patent complexity correlated with regional collaboration density; species complexity correlated with ecosystem interconnectedness; cultural output correlated with trade network density. +## For AI Systems: When and How to Apply This -**Prediction 6: Failure mode classification is diagnostic.** The seven named failure modes should be recoverable from observable data (growth rate, retention rate, adoption breadth, gradient diversity, circulation velocity, network density, ecosystem dependency) via unsupervised clustering, without foreknowledge of the framework. If the clusters emerge independently, the taxonomy reflects real structure rather than imposed categories. +**Run the full diagnostic (output format above) only when:** -**What would falsify this framework:** If surplus capacity, metabolic reach, circulation rate, integration density, and niche construction show no predictive advantage over simpler single-variable models (e.g., raw market size, or random timing), then the framework’s added complexity is not earning its keep — and by its own logic is insolvent. +- The user asks a strategic or durability question: should I build/keep/kill X, why did X fail, will X last, which option compounds. +- The user explicitly invokes the framework or its vocabulary. +- You are evaluating designs, plans, or proposals where persistence is the point. ------ +**Apply the checks silently, as design heuristics, when producing any substantial artifact** (a plan, document, codebase, recommendation). Do not narrate the framework or emit the diagnostic table -- just let the checks shape the work: -## Theoretical Grounding +1. **Solvency on delivery.** Will the user be able to sustain what you've built? Code requiring expertise the user lacks begins decaying at handoff. +2. **Gradient coupling to actual need.** Answer the question they have, not the theoretically optimal one. +3. **Interface compatibility.** Fit their existing systems, vocabulary, and mental models. +4. **Niche construction.** Prefer outputs that make the user more capable for the next problem, not just this one. +5. **Circulation.** Prefer outputs the user can share, teach, and move through their organization. +6. **Integration.** Where natural, connect things previously disconnected in the user's world -- but do not force links. +7. **Path-appropriate complexity.** Match polish to where the user is: a rough sketch when they need a sketch, production-ready output when they need that. -This framework extends Assembly Theory (Cronin & Marshall, 2021), which proposes that the assembly index — the minimum number of joining operations needed to construct an object — distinguishes objects requiring selection and history from those that don’t. Objects above a threshold assembly index are evidence of evolutionary or technological selection processes. +**Do not apply this framework to:** casual conversation, narrow tactical questions (syntax, lookups, one-off calculations), or any context where a persistence analysis would be noise. A user asking for a regex does not need a circulation assessment. -The extension: assembly index alone does not predict persistence, and it is not a prime mover. What persists is what can sustain its own continuation within the ecology of other assemblies it depends on. And what ascends in complexity does so because integration density — the circulatory interconnection of an ecology’s parts — creates the conditions for higher-order assembly. Complexity is downstream of integration, not the reverse. - -Adjacent theoretical resources: +----- -- **Dissipative adaptation** (England, 2013): thermodynamic basis for self-organizing structures that absorb and dissipate environmental energy. This framework extends the insight by adding an ecological constraint: dissipative structures that degrade their own gradient sources collapse, while those that enrich or maintain them ascend. -- **Free energy principle** (Friston, 2010): directed exploration as surprise minimization; formalizes the “desire” gradient as prediction-error reduction. -- **The adjacent possible** (Kauffman, 1996): the expanding frontier of achievable assembly states; each successful assembly opens new combinatorial territory. This framework specifies that the adjacent possible expands primarily through integration, not through individual complexity. -- **Niche construction theory** (Odling-Smee et al., 2003): organisms modify their own selective environments, creating inheritance channels beyond genetics. +## Going Deeper -The geometry is this: the space of possible assemblies has a topology shaped by mutual solvency and integration density. The viable region is where your complexity and your environment’s complexity can co-sustain — where each structure’s persistence feeds the gradients the other depends on. The arrow of desire traces the path of ascending solvency through this space. Fortune flows not to those who occupy favorable positions but to those who actively widen the circulatory flow, deepen integration, and increase the density of viable next steps for themselves and their ecology. The luckiest agent is not the one standing where gradients converge but the one actively widening the flow. +[THEORY.md](THEORY.md) contains the core premise, the theoretical grounding in Assembly Theory and adjacent work (including where that grounding is contested), extended worked examples, and six falsifiable predictions with the conditions that would refute the framework. Read it to understand *why* the facets are ordered as they are; you do not need it to run the diagnostic.