Published note
The Hickeyian Way
Before adding machinery, ask which ideas have been tied together that should vary independently. Split those first, then build the smallest proof that the split made the system easier to reason about.
This started as a phone note about the Rich Hickey way of thinking: simple is not the same as easy.
Easy is the thing close to hand. Add a field. Add a flag. Add another kind. Add a mode. Add a little adapter. Ship it.
Simple is different. Simple asks whether two ideas have been braided together. If they have, the work is not to add more cleverness. The work is to separate them until each thing can vary without dragging the others around.
That is the bit we need when building with AI agents.
AI makes easy very easy. It can generate screens, schemas, services, queues, docs, and test harnesses quickly. That is useful, but it also means a product can collect accidental complexity faster than a human can notice it.
So the review question becomes:
What things have been tied together that can vary independently?The Smell
A design is probably getting complected when one object, command, or service starts carrying several different kinds of truth:
- what the user wants
- what facts are known
- what can be computed
- what implementation is available
- what permission has been granted
- what safety policy applies
- what UI is being used
- what proof says this works
- what should happen after failure
Any one of those can be legitimate.
The problem is when they are fused into one blob because that was the quickest way to move.
In Commandbook, we almost did this with commands and capabilities. It was tempting to make a command say what it is allowed to do. That sounds tidy, but it ties the recipe to the local device, the runtime policy, and the human’s permission history.
Those are separate things.
A command should describe the job.
An operation should declare the concrete capability it needs.
The runtime should enforce grants.
The human should be able to approve, revoke, or run in a trusted mode.
Those pieces interact, but they are not the same piece.
The Move
The Hickeyian move is not “make more abstractions”.
It is:
- Name the concepts.
- Ask which ones vary independently.
- Split only at real variation or enforcement boundaries.
- Keep the records boring.
- Prove the split helped.
That last step matters. Complexity does not become good complexity because it has a clever name. It earns its keep through a feedback loop: fewer bugs, clearer tests, easier recovery, or a smaller mental model.
This is why “only complexify for improvement” has become a core Continuum rule.
Do not add machinery because the idea is elegant.
Add machinery when the existing system has shown a real pressure point and the new boundary gives us proof.
The Practical Checklist
When a plan starts getting big, run a decomplex review:
Hickey Decomplex Review: <scope>
Verdict
<one sentence>
Already Simple
- <good split>
Complected / At Risk
1. <tangled concept> - <why tangled> -> <split>
Next Slice
<one small record/schema/test/docs change>Good splits tend to look like plain data:
GraphEdgeImplementationBindingCapabilityRequirementCapabilityGrantSafetyPolicyProofClaim
Bad splits tend to look like one universal provider object with kind, driver, permissions, tests, UI, setup, runtime, and recovery all inside it.
That kind of object is easy to create and hard to understand.
Why This Matters More With Agents
The old bottleneck in software was often writing the code.
The new bottleneck is deciding what should exist.
If the human and the agent skip that thinking, the agent can faithfully build a confusing product very quickly. Every prompt feels productive. Every feature looks plausible. Then, a week later, no one knows what the product is.
The better use of agents is not “make more stuff”.
It is “make reality visible”.
Use agents to:
- read the docs
- compare the app to the docs
- find tangled concepts
- produce small candidate splits
- write tests around the pressure point
- delete accidental machinery
- generate honest product language from the actual product
That is the Continuum version of the Hickeyian way:
separate the things that vary independently, prove each extra moving part earns its keep, and keep the product surface small enough that a tired human can still understand it.
Source Note
The original phone-side ChatGPT article titled “The Hickeyian Way” was only partially captured: the scrape retained the title and shell text, not the full body. This public note is therefore a fresh Continuum Kit write-up based on the same idea, the Commandbook architecture discussion, and the decomplex review we ran on 2026-06-08.