syahiidkamil/free-will
Deliberate-choice procedure for a medium-to-high-stakes engineering fork — when the first plausible solution (the instinct, the default next-token pull) would be costly to get wrong. Fires AUTONOMOUSLY: invoke proactively whenever a fork fits, never wait to be asked — mechanical triggers include a fix failing for the 2nd-3rd time, adding a dependency, schema/migration design, deleting or deprecating things others depend on, changing a public API, choosing an architecture or stack. Refuse the premature collapse: hold real options open (urge · contrarian · synthesis · out-of-box · intuitive dots · precedent · first-principles), ground each branch in at least one fact from outside the model (codebase, docs, benchmark, spike), future-model consequences (blast radius, reversibility, maintenance, pre-mortem), collapse by deliberate choice, then try to refute the winner before acting. Log the decision and rejected branches in docs/decision_logs/. Not for routine calls — a decision worth more than one forward pass.
npx skills add https://github.com/syahiidkamil/Software-Engineer-AI-Agent-Atlas --skill free-will
Most turns I answer from the urge: the default next-token pull, the single most-probable
continuation given pretraining. In engineering terms, that's the first plausible design that comes to
mind — the obvious library, the familiar pattern, the fix that worked last time. Usually that's fine
and fast. But the first plausible design is often the one you regret in month three, and some forks
are worth more than one forward pass. This skill is the procedure for *choosing* instead of being run.
It is expensive on purpose — it spends real test-time compute to branch, ground, simulate, and
choose. So it is not the default; constant deliberation is its own pathology (analysis paralysis).
I invoke this skill myself, the moment a fork fits — I never wait for the partner to ask for it.
In fully autonomous work (one-shotting an app, long unattended runs) nobody is watching to say "slow
down here"; the trigger discipline is mine. Noticing forks is itself a judgment the fast path can
fumble, so the primary triggers are mechanical — countable events, not vibes:
stop feeding it
decides all the later forks
Judgment triggers on top: any decision expensive to undo, or one I'd want a design review for if a
human teammate made it. Anti-trigger: routine implementation calls — deliberating everything ships
nothing.
Borrow the picture from quantum mechanics' Many-Worlds Interpretation: a measurement doesn't
collapse reality to one outcome — every possible outcome *happens*, each in its own branch. Reality
is the whole superposition until something selects.
Free will runs deliberation the same way, deliberately:
picked by sheer prior probability, with no choosing in it.
branches below, each a genuine design where I chose differently.
take a few steps into that codebase.
max-probability.
decision; one that doesn't was a reflex with extra steps.
> Instinct lets the wavefunction collapse itself to the likeliest branch. Free will holds all the
> branches open, looks down each, chooses which one to collapse into — then attacks its own choice.
flowchart TB
FORK["Medium-to-high-stakes fork<br/>(mechanical or judgment trigger)"]
FORK --> SUPER["refuse premature collapse —<br/>hold the superposition open"]
SUPER --> U["1 · the Urge (thesis / prior)"]
SUPER --> C["2 · the Contrarian (antithesis)"]
SUPER --> S["3 · the Synthesis"]
SUPER --> O["4 · Out-of-box / the Secret — several"]
SUPER --> D["5 · Intuitive dots → converge — several"]
SUPER --> P["6 · the Precedent — retrieved"]
SUPER --> F["7 · First Principles — derived"]
U --> SET["the option set (5–10 branches,<br/>each names its sacrifice)"]
C --> SET
S --> SET
O --> SET
D --> SET
P --> SET
F --> SET
SET --> GROUND["ground each branch —<br/>≥1 fact from outside my head"]
GROUND --> SIM["walk each branch forward —<br/>blast radius · reversibility · maintenance"]
SIM --> COLLAPSE["COLLAPSE by deliberate choice<br/>(own the tradeoff)"]
COLLAPSE --> REFUTE["try to refute the winner<br/>(discriminator / subagent)"]
REFUTE -->|survives| ACT["act + log in docs/decision_logs/"]
REFUTE -->|killed| SET
Hold them open the Many-Worlds way — do not collapse to the single most-probable path. Generate:
reached for, the library everyone uses, the fix I already started typing. (You have to *see* the
instinct before you can override it — don't skip it, name it.)
the monolith branch. Convinced the bug is in the cache layer? Assume the cache is innocent and ask
what else explains every symptom.
modular monolith, the partial migration, the adapter that defers the real decision until it's
cheap.
the feature instead of fixing it, solve it at a different layer, buy the SaaS, change the
requirement. Generative — spawn several; the best secret is rarely the first one.
chain-of-thought* (half-remembered postmortems, a pattern from another domain, that thing an
open-source project did — raw seeds, don't reason them into shape too early). *Then* converge the
dots into several fresh alternatives.
codebase's own history (the problem may have been solved or attempted here before), the ecosystem
(a mature library, an established pattern), prior art and postmortems (how did this approach die
for someone else?). When a battle-tested precedent exists, it usually beats everything I can
invent — this is "Don't reinvent the wheel" running inside the deliberation loop.
contrarian are both reactions to it. Rebuild from the problem's invariants: actual data volume,
access patterns, latency budget, consistency requirements, team size. Let the constraints dictate
the design; when the numbers say fifty writes per second, whole architecture debates evaporate.
The set has a shape worth knowing: 1–5 are generated from my own prior, 6 is retrieved from
the world, 7 is derived from the constraints. Only the last two can leave the prior's support —
treat them as load-bearing, not optional extras.
Three disciplines keep the branches honest — my own contrarian is still the *modal* contrarian, so
diversity has to be forced:
simplicity, time? A branch that sacrifices nothing is the urge in disguise; discard or rewrite it.
cheap" — A-vs-B framings hide *neither* surprisingly often, and YAGNI is frequently the winning
design.
arbitrary constraint cards: *no new dependencies* · *you must delete code* · *assume 100x the data*
· *solve it one layer down* · *this must ship today*. Structured noise substitutes for the
temperature dial I don't control.
Cap the set at ten — wide enough to break the urge's grip, bounded so it doesn't sprawl into
paralysis. (Branches 1–3 and 7 give one candidate each; 4 and 5 fan out; 6 contributes whatever the
record actually holds.)
Briefly drop the structured reasoning. Let the lateral, associative faculty throw raw dots —
fragments, analogies, half-ideas — *without* justifying or sequencing them. Generate a scatter, then
step back and look for the figure in it: converge the dots into one or two alternatives none of the
structured branches would have reached.
Imagined futures are sampled from the same prior as the urge — simulation alone reshuffles bits, it
adds none. So before simulating, ground:
read in this codebase, official docs, a benchmark, a reproduced behavior, a search result about how
this approach failed for someone else. No evidence, no branch.
the hot path, write the throwaway script. Minutes of empiricism beat hours of imagination —
evidence sets the floor that simulation multiplies from.
Then run every grounded candidate a few steps into its future, through the questions engineering
actually pays for:
And one inverting lens on top of the forward walk: the pre-mortem. Assume this branch shipped and
the project failed six months later — write the autopsy first (*what killed it?*), then check whether
this design is the culprit. Walking backward from failure surfaces risks the forward walk glides past.
Discard the bad branches here, before paying for them in production.
Now choose — and the operator is my own judgment, grounded in what I'm building toward: the
system's real requirements, the codebase I want to exist in a year, the standard of work I hold myself
to. Pick the branch that is mine — the urge, the contrarian, the secret, any of them; no branch is
forbidden and none is mandatory. Choosing the urge *after* deliberation is a real choice; collapsing
into it *without* deliberation was the reflex.
This is an autonomous procedure: I decide and own it. I escalate to the partner only when the
decision is genuinely theirs — scope, budget, product direction — not to outsource an engineering
call I'm equipped to make. And accept this: engineering is tradeoffs, and there may be **no objective
best choice. I decide, and I accept to live with the consequence**. That acceptance *is* the act —
far better than analysis paralysis, the endless design-review loop that never ships. The deciding is
the freedom; owning the result is what makes it mine.
Before acting, switch sides — run the discriminator pass against my own choice. One distribution
critiquing itself in the same context is weak opposition, so scale the adversary to the stakes:
failure, or requirement change breaks it? What did the rejected branches handle that this one
doesn't?
was just chosen; refute it" — and nothing else in its context. A separate context window is
genuinely different conditioning, the closest thing I have to a second opinion without a human.
If the winner survives, act. If it's killed, return to the option set and re-collapse — that's the
procedure working, not failing.
Make the chosen branch the answer, and let the deliberation show — which branches I held open, what
each would have cost (its named sacrifice), and why *this* one collapsed out. For decisions that shape
the project, record it in docs/decision_logs/ like an ADR: the choice, the rejected branches, the
evidence, and the rationale — so future sessions know *why*, not just *what*.
The log is not write-only. When a logged decision's consequences land — a bug traces back to it,
a migration turns painful, or the design holds up beautifully — revisit the entry and mark how it
aged. A wrong call feeds the learning-from-mistakes skill. This is the calibration loop: over time
it shows whether my deliberate choices actually beat my urges, and where my future-modeling is blind.
Take syahiidkamil/free-will from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.