DEV Community: Miguel Shinyenyi

Building the Umwayi hub landing page on Founding.dev: what happened and how we responded

Miguel Shinyenyi — Mon, 09 Nov 2026 19:24:22 +0000

I build the Umwayi hub in public. It is an AI operating system that grew out of my personal notebook. One backend engineer in Nairobi builds it, and it is pre-release. The code has no front door, so for the Founding.dev design hackathon I designed one.

Live page: https://umwayi-hub.foundingdev.com/

What the page is for

A stranger should understand the hub in one minute. The headline is "Every AI helper needs a shepherd." The hub gives every AI helper one of three answers before it acts: Yes, No, or Ask me first.

I did not want a mock-up. The demo on the page shows the real hub as it exists: its rules, its queue, its archive and its logbook, taken from the public repository. The build window ran from Nov 6 to Nov 10, about three hours a day.

How the build went

I planned the page with Claude before I touched the builder. We wrote the prompts in advance, one at a time, so each one could stand alone.

Prompt 1 built the page: hero, timeline, four parts, roadmap, FAQ.
Prompt 2 built the demo from real hub content.
Prompt 3 added the dark theme, Nightwatch.
Prompt 4 finished the roadmap and FAQ.
Prompt 5 audited the page.
Prompt 6 turned the four parts into one hill scene you can walk into.

The first paste went wrong. The builder sent only the first line, because a line break submits the message. From then on we pasted every prompt as one line.

What went wrong on screen, and what we did

The builder reports what it saw, and it often saw one view. So after each prompt I looked at the page myself and wrote down what was wrong. The next prompt fixed exactly that.

Robot shepherd, gate lamps and a logbook printer went in on Nov 7. The lamp labels were about 6.5 pixels tall and unreadable, and a lamp plate overlapped the robot's arm. When the lantern became the robot's head, the night lantern disappeared.
The next pass added a conveyor belt and a vault barn. The lamp sign came out far too large, nearly as tall as the fence. The robot, barn and fence were different scales. The barn door overlapped its shelves.
Prompt D set one scale for every object and added scroll motion. The Parts scene was still about 60 percent empty sky, with small objects in a strip at the bottom.
Prompt E cropped the sky and scaled objects up by about 1.5. Two sheep were left floating above the fence.
Prompt F put everything on one ground line. Three hero sheep still merged into one shape, and the robot overlapped the end of the pen fence.
Prompt G fixed the hero crop and the sheep spacing, and made the Parts scene fit at 375 pixels.

Six passes, and each one fixed what the one before it left. The builder's own report did not catch most of these.

How we kept it safe to change

After every prompt I wrote down the commit and what it changed, so I could go back. Every pass has a restore point. If a prompt made the page worse, I could revert to the commit before it.

I also set a credit rule. The hackathon gave $10 of builder credits, plus extra I added. I set a $3 reserve. Each machine-imagery prompt cost about $0.40. When a text pass needed more, I approved going below the reserve myself, so the decision stayed with me.

Keeping the page honest

The page started with a rule: it may not claim more than the hub does. Helpers are marked as coming, not built. Roadmap dates carry the label "Plan, dates may change." Nothing on it is marked live.

The hub moved while I designed. On Nov 7 I found wording that said the hub was one check. It was code in layers. We rewrote the text. On Nov 8 we replaced the roadmap with six cards that match the real timeline. On Nov 9 we updated the text to the current phase of the hub.

Where it is weak

The builder reported one view at a time, and I checked the night view at desktop width after each pass. The light theme on a phone works; I have confirmed that. I have not confirmed the page at night on a phone, or at tablet width, after the last changes. Look at it yourself in both themes and at three sizes.

I also left the Helpers heading as it was written on Nov 7. The roadmap has moved since, and the two no longer say the same thing.

What I took from it

Write the prompts first, and send them one at a time.
Look at every result yourself. The builder reports the view it saw.
Keep a restore point after each change, and a credit limit you decide.
Keep the page text in step with the real work.

The page is published. The hackathon closes Tue Nov 10, 10:59 AM Nairobi. The build story of the hub itself comes with my Kiroween submission on Dec 3.

The code: https://github.com/Miguel-Shinyenyi/umwayi-os

If you have used an AI page builder, what did you have to fix after its first pass?

Originally published on my site.

Appearance versus reality, from three lines in an interview

Miguel Shinyenyi — Mon, 09 Nov 2026 07:25:35 +0000

The source

In late November 2025, Nikhil Kamath interviewed Elon Musk on his People by WTF podcast. I wrote down three ideas from it in my notes. Before I used them, I looked for reports of the interview. Two of the three held up. One detail in my notes did not.

I am quoting a public figure on ideas, not endorsing him. I did not check his own record. These ideas stand or fall without it.

Idea one: appearance and reality

Reports of the interview say he called it easy to give money away to get the appearance of goodness, and hard to give it in a way that truly helps. I see the same split in my own work.

A commit count is an appearance. So is a count of merged pull requests. Both can rise without helping anyone. The reality is whether the reporter's problem got solved, and no git log records that. In my open-source work, a pull request can merge and leave the reporter's problem open. Another can close unmerged because the maintainers shipped their own fix, and the problem is still solved. The count rates the first higher than the second. The reporter would not.

Idea two: happiness is indirect

He said you cannot pursue happiness directly. One report names meaningful work, study, and time with friends and loved ones. My note says "going to the gym". None of the sources I read mention the gym, so I cannot attach it to him. It is a good example anyway, so I am keeping it as mine: I do not get happy by trying to be happy. I get there by sleeping, moving, and seeing people I like.

Idea three: value first, money after

His advice, as reported: build useful products and services, and money follows. Create more value than you take. My note says "output more than you input". I read this as a test for a project, not a promise of income. Ask who gets something useful from it. If the honest answer is "only me, and only on paper", it is probably not worth the hours.

What I changed

I added a progress digest to my hub. It counts commits and merged pull requests by week. It cannot count value. Its README says so, and I read each digest next to my journal, where I write what actually got solved.

What I might be wrong about

A person with enormous wealth may talk about money differently than someone building from nothing. These ideas may not transfer cleanly.
Money does not always follow value. Useful work often goes unpaid. I read the idea as a direction.
I read reports, not the full recording. Quotes in articles can be trimmed or reordered.

What I took from it

Counts of activity show appearance. Whether someone's problem got solved shows reality.
I cannot pursue happiness directly, so I keep the habits that lead toward it: sleep, movement, people.
For any project, ask who gets something useful from it besides me.
If I cannot verify a detail in my notes, I mark it as mine or I drop it.

Originally published on my site.

Do the rules that stop an AI also stop us?

Miguel Shinyenyi — Sun, 08 Nov 2026 05:06:02 +0000

What this is

These are my notes from November 8, written after reading parts of Sapiens by Yuval Noah Harari and while building a rules layer for AI helpers. I am not a neuroscientist or a machine learning researcher. The claims about brains and models are my understanding, and I mark where I am unsure. I have not checked the Sapiens points against the book page by page.

The comparison I started with

An AI model is trained on a large amount of text. Training sets numbers called weights, and the weights shape what the model says next. A person is raised among people. Family, school and culture shape what the person believes and what the person does next.

Both end up with something that works like a settled view. Neither can fully predict what it will output in a new situation.

Where the comparison holds

Both are shaped by what they were exposed to. A model trained on poor text gives poor answers. A person raised on poor information holds poor beliefs.
Both can be wrong with confidence.
Both can produce something their history does not predict. A person can drop the beliefs of their upbringing. A model can produce text that no reliable source supports. These are different events, and I do not treat them as the same.

Where it breaks

As far as I know, a model does not visibly weigh an earlier belief against new evidence. When it hallucinates, it produces fluent text that is not grounded in a reliable source. Some models carry internal signals about their own uncertainty, so I will not say there is nothing behind the text. A person who changes a belief usually felt the conflict first. I do not know whether a model has anything like that feeling. As far as I know, nobody has shown that it does, so I will not claim it.
A person keeps learning after childhood, from one experience at a time. A deployed model has fixed weights. Inside one conversation it can adapt to what you tell it, but that is not learning, and it is gone when the conversation ends.
Determinism is not the same on both sides. A model run with fixed settings can give the same output twice, but it is not guaranteed in practice, because of rounding in floating point math and how requests are batched together. For brains, whether they are deterministic is still an open argument. I will not settle it here.

So I would say the model resembles a person in how it was shaped. It does not resemble a person in how it changes its mind.

What the rules do

When I build checks around an AI helper, I write down what it may do, what it may not do, and what it must ask me first. The check runs as code. If the action is not listed, the answer is Ask me first.

Harari describes imagined orders: money, empires, religions. They work because many people believe in them. I recorded his argument like this: cultures that were once separate and isolated were drawn together by universal orders, the monetary order, the imperial order and religion, and money succeeded where gods and kings failed. The line I added myself is that money feeds the body while religion and politics mostly comfort the mind. I do not know whether that last part is his.

Here is the difference I keep coming back to. An imagined order needs belief. It also needs people to enforce it, and people sometimes do not. A rule file in my system needs neither. The model does not have to agree with it. The check runs outside the model. The model cannot talk its way past it, as long as it cannot edit the rules file and cannot act without going through the check. Both of those conditions are things I have to build and test.

The two are alike in one place. Someone wrote the rules. Someone decided what was allowed. The check is exact, but the choices behind it are human, can be wrong, and can be changed. That is also true of laws.

What a rule gives back

I wrote down another note this week. A kite flies when it is tied to a string, and it falls when the string is let go. Something I take as holding me back may be what lifts me. I try to notice which of my limits work that way.

A rule that stops an AI from moving money lets me give it other work without watching every step. The limit is what makes the trust possible. In my own life, a fixed schedule has done the same.

Harari also says tension and unresolved dilemmas drive creativity in a culture. I think a system needs some of that too. My rule file answers every case, but the cases I did not list go to me. That keeps a human decision in the places that are new.

What I still do not know

Whether a model can hold two conflicting views in a way that matters, or whether that is only how its output looks.
Whether a checker outside the model could ever be complete. Mine is not. It fails safe, and that is a weaker claim.
Whether the rules I write for helpers say more about the helpers or about me.

Originally published on my site.

Come with a question, not a verdict

Miguel Shinyenyi — Sun, 08 Nov 2026 05:05:31 +0000

The verdict is already written

I have been paying attention to how arguments go, mine included. Someone says a first sentence. The other person has the reply ready before the sentence ends. The reply is a verdict. It only needs a signature.

A verdict ends the inquiry. If I already know you are wrong, I have no reason to learn why you think what you think. I wait for my turn. You do the same. Two people can talk for an hour and neither learns anything.

What a verdict costs

It costs me information. The person across from me holds facts I do not have: what they saw, what they lost, what they read. A question gets me those facts. A verdict gets me a defended position.

It also costs them. In my experience, people who feel judged often stop explaining and repeat their position louder. I then read the louder repetition as proof I was right. That is how the loop feeds itself.

I suspect curiosity dies this way, one conversation at a time. Nobody may decide to stop being curious. People may learn that questions get punished and verdicts get rewarded.

A check to run before I reply

I am trying three steps. They are small on purpose.

Say the other person's view back to them in my own words, and ask if I got it right. If they say no, I was about to argue with something they never said.
Ask one question whose answer I do not know. "What would change your mind?" works. So does "What did you see that made you think that?"
Name what would change my own mind before I speak. My view is that if nothing could, I do not have a position. I have a verdict.

In my first tries it took about two minutes. It does not mean I agree. I can ask a real question and still disagree after I hear the answer.

What I might be wrong about

Some questions are settled. If someone says the earth is flat, a long curious conversation may waste both our time. I do not have a clean rule for where that line sits.
A question can be a verdict in disguise. "Don't you think that's a bit naive?" is not a question. Asking well takes more than adding a question mark.
I have tested this on myself in a few conversations, not on a large sample. The effect I describe is what I noticed, not something I measured.
Some people argue to win, and no question will change that. I still choose how I show up. I cannot choose how they do.

What I took from it

A verdict ends the inquiry before it starts. A question keeps it open.
People often stop explaining when they feel judged, and I then take their louder repetition as proof I was right.
Before replying: restate their view, ask one question I cannot answer, and name what would change my mind.
Asking a question does not mean I agree. It means I want the facts first.
If I cannot name what would change my mind, I am holding a verdict.

Originally published on my site.

A Folder Is Not a Brain Until You Measure It

Miguel Shinyenyi — Tue, 03 Nov 2026 08:05:01 +0000

What I wanted

I wanted an AI that acts on what I mean, not on the first reading of my words. I wanted it steady and quiet when I am rushing.

So I built a folder. It holds a short identity, rules that came from mistakes, a habit of understanding a problem before solving it, and an archive. I called it a brain. I thought of the archive as childhood memory: vague, but still part of who I am.

That was a belief, not a result. This article is what happened when I checked it.

What the studies say about eager AI

Eager execution is measured now. I did not need to argue it.

One benchmark ran about 7,500 coding-agent runs on tasks where doing extra was wrong. The mean rate of out-of-scope actions was 10.8%. The same base model ranged from 1.1% to 27.7% depending on the tool wrapped around it.
Another benchmark gave agents underspecified infrastructure instructions. Between 55.8% and 67.8% of the runs that acted crossed a boundary.
A third paper added a second agent that watches for missing context and forces a question. Resolve rate rose from 61.2% to 69.4%. Cost per task rose from $2.03 to $3.50. The user in that test was simulated.

Eager execution is real, large, and depends on the harness as much as the model.

What the studies say about folders like mine

A 2026 study tested repository context files, the AGENTS.md kind, on coding agents.

Files written by a model lowered success by 0.5% to 2%.
Files written by a developer raised success by about 4%.
Both kinds raised reasoning tokens by 14% to 22%.

The agents obeyed the files. The files that restated what the repository already said did not help. This matters to me. A model drafts much of my hub. A file I never read closely can cost more than it gives.

On identity, persona research finds drift. One study saw a model leave its system prompt within eight rounds. Another ran more than 100 rounds and saw personas revert toward the model's default. Larger models drifted less, and none stayed fixed.

What others already built

My design is not new. Letta, which grew out of MemGPT, splits in-context core memory from archival memory. It also runs a second agent that rewrites memory while the first one is idle. Anthropic's memory tool gives the model a directory of files it can read and write. A 2026 survey of agent memory says forgetting is rarely tested and warns of memory blindness, where an important fact sits in cold storage and is never fetched.

If I claim a new architecture, I am wrong. If I claim a measured result on one open model, I can be right.

Where my human memory comparison fails

Some of it holds. A small core that is always loaded, plus a store reached by cues, is a sensible answer to limited working capacity. One review of memory research describes detailed episodes turning into gist-like versions over time. Another line of work says gist and exact detail are stored in parallel.

Three parts do not hold.

A person's early experience keeps shaping them because the brain changes. A model's weights do not change. An archived file that nobody loads has no effect at all.
Human gist comes from lossy storage and produces false memories. My archive can be exact. So I should keep the original text, and mark every summary as derived and link it to its source by checksum.
In people, recalling a memory can alter it. Each time I rewrite my core file, I risk the same. A rule written from one mistake can lose its conditions and grow too broad.

I now use the comparison as a reason to try a design. I do not use it as proof.

What I think is true now

One narrow claim looks supported by nearby evidence: short, human-written rules and a stated scope can cut out-of-scope actions. The effect is small, depends on the harness, and costs tokens.

Two bigger claims are not supported. A folder does not make a brain. A text file does not give an AI an identity. It gives it a policy and a style. If I say more, I owe a measurement.

Where I will test it

I joined the Meta Global AI Developer Hackathon, which runs from October 27 to November 4, 2026. I entered as a solo builder in the Indie track. Entries must use Meta models. I will use Muse Spark Open, an open-weights model, served on Baseten.

I will not test the folder on its own. A test with no user is easy to bend toward the answer I want. I am building a small open-source secretary for savings groups, the chamas many Kenyans use to save together. A treasurer speaks a note or photographs a paper ledger page. The agent proposes ledger entries and asks a question when a note is ambiguous, for example when two members share a name. The treasurer approves everything. The agent moves no money, scores no one and sends nothing.

The restraint ideas from this article sit inside that agent. The tests are part of the entry, with the plan and protocol public in the repository before I run them. I have not built any of it yet. People already make chama apps, such as Chamasoft and M-Chama, so I am not claiming this is the first. Nobody has used mine. Whether treasurers want it is a question I still have to ask them.

What I will test

I will run it on Muse Spark Open in the first week of the event, with the hypotheses written down first.

Curated rules lower wrong guesses on ambiguous notes, such as a name that matches two members. The comparison that counts is against a generic "ask when unsure" block of the same length, not against nothing.
A core plus a traceable archive keeps stale-fact updates and archived needles better than truncation or plain retrieval at the same token budget.
Rule adherence survives compaction, when a long conversation is summarised to continue.

Controls: a placebo text of equal length, scenarios split into development and a frozen test set, a check that the model does not simply always ask, and cost reported next to every effect. With about 40 test scenarios I can only detect effects of roughly 15 points or more. A null result gets published.

What I do not know

How Muse Spark Open follows instructions, and whether it reads handwriting and voice well. I check this on day one.
Whether treasurers want this at all.
Whether my rules fit my own test cases because I wrote both.
Whether any effect survives a second model.

Sources

I read the abstracts or summaries of the memory-science sources, not the full papers.

What I took from it

Check a belief against studies before building more on it.
Keep rules short, human-written and specific. A file that repeats what the repository says costs tokens and adds nothing.
Compare against a placebo and a generic version. Beating nothing proves nothing.
Keep the original text, and link every summary to it. An AI can be lossless where a person cannot.
Say "persona and rules file" until a measurement earns the word "identity".

Originally published on my site.

Stay Close Behind the Code

Miguel Shinyenyi — Mon, 26 Oct 2026 11:11:32 +0000

What I notice

AI writes more code in an hour than I can read in a day. When I watch the volume grow, I feel pressure. Other people seem to ship more. I feel I should add more tools, more agents and more lines.

I wrote this from my own notes. I have not checked them against a study or a talk. They describe what I see in my own work.

Three feelings behind the hype

Code carries the feelings of the person who wrote it. Three feelings sit behind the hype.

Code written in a hype cycle carries desperation and fear of missing out. I wrote it fast because I thought I would fall behind. I cannot tell you why it works, so I do not trust it. Nobody else trusts it either.

The third feeling is overwhelm. There is so much to do, so many tools to learn and so much new code to read, that I end up doing nothing. I think this feeling is one cause of the hype, not only a result of it. It pushes people to chase the next thing because finishing a small thing feels pointless next to the pile. I have not checked that. It is what I see in myself.

Code I understand carries a calm kind of feeling. I know what it does and where it stops. That feeling takes time to earn. It does not come from volume.

For code to be worth something to another person, it needs my time and my feelings in it. I cannot add either by prompting faster.

Let AI write it, and stay close behind

I do not say you should write every line by hand. Let AI write the code. Stay one step behind it and understand each part as it appears.

My order is this.

Understand the people. Problems come from patterns where people struggled.
Write the code, preferably with AI.
Stop and check that the output matches what I meant.

The third step is the hard one, because I cannot measure "what I meant" until I have said it in one sentence. Patterns, constants and outliers also take time to see. If I rush, I miss all three.

If I only write code, I should ask who I am helping.

The cycle I follow

Every step I take goes round the same cycle.

Understand things as they are, not as I want them to be.
Let AI write the code for what I understood is needed.
Check that the output matches what I meant.
Weigh the consequences before I act. Every action has some. I want the change to do more good than harm, and I want to know how to undo it.

Then I start again with the next step. The first step is the hard one. When I want something to be true, I read the code as if it already were. The ledger check below exists because a system cannot afford that wish.

A check that stops the work

My settlement engine has a check that makes the work stop. Each account stores a balance, and each account has ledger entries. The two must agree. This is the service that compares them:

public void verify(LedgerAccount account) {
    BigDecimal computed = ledgerEntryRepository.sumNetByAccountId(account.getId());
    BigDecimal stored = account.getBalance();
    if (stored.compareTo(computed) == 0) {
        return;
    }

    if (ledgerMismatchRepository.findByAccountIdAndResolutionStatus(account.getId(),
            MismatchResolutionStatus.OPEN).isEmpty()) {
        ledgerMismatchRepository.save(new LedgerMismatch(UUID.randomUUID(), account.getId(), stored, computed,
                "Stored balance " + stored + " does not match net of ledger entries " + computed));
    }
    throw new LedgerInconsistencyException(account.getId(), stored, computed);
}

When the numbers differ, it records the mismatch for a person to review, and then it always throws. The caller never receives a balance the ledger does not back. The account endpoint runs this check before it does anything else with the account.

This code does not help me ship faster. It makes me stop and ascertain. It is the same habit I want in my own work: before the next step, check that this one matches what I meant.

I verified the code above against the repository on 2026-10-16. I did not run it for this article.

A step I skipped

On 2026-07-11 I committed a file called mvnw. It looked like the Maven Wrapper. It was four lines that pointed at one folder on my own machine, because I had no system-wide Maven on that machine.

# shortened
MVN_HOME="$HOME/.m2/wrapper/dists/apache-maven-3.9.9-bin/.../apache-maven-3.9.9"
exec "$MVN_HOME/bin/mvn" "$@"

It worked for me. It failed on the first CI run, because that folder does not exist on any other machine. I fixed it on 2026-07-17, six days and 23 commits later, by regenerating the real wrapper. The notes in the project say what went wrong: I replaced the wrapper when I only needed to fix my path.

I see two of the failure modes below in that story. I skipped a step, and I put a patch on a problem I had not understood.

Eight ways I get lost

These are the names I use. Each has a sign and a remedy.

Forming. The right question, the wrong answer. I ask more questions until I know the goal and how to approach it.
Dislodging. I am stuck in a rut. I accept that the approach is not working and restart.
Assumption. The wrong question, the right answer. I go back and understand the goal.
Location. So close, so far. I skipped an important step. I slow down and take every step.
Achievement. A band aid on a broken bone. If the whole codebase is poor, I rewrite it.
Progression. I fall behind without noticing, because AI took over code I do not understand. I stop and read.
Interruption. Someone breaks the train of thought that was finding the goal. I know the goal best, and I deal with the humans.
Mislead. A suggestion leads me away from the goal. I check each suggestion against the goal first.

What I took from it

This list is a draft for me to correct.

Understand things as they are before I change them. Then let AI write what I understood is needed.
Every action has consequences. I weigh them and know how to undo the change before I ship it.
The little work I do each day is what matters. Hype does not change that.
Protect my energy. Do not chase the volume.
When there is so much to do that I do nothing, I pick the smallest next piece and finish it.
Hyped code carries fear and desperation. Code I understand carries good feelings, and those take time.
Let AI write the code, and stay close behind it.
Understand the people first. Then write. Then stop and check the output against what I meant.
Build checks that make the work stop and ascertain, like the ledger check.
Name the failure mode when I notice it, and apply its remedy.

Originally published on my site.

My First Agentic System Is a Folder of Files

Miguel Shinyenyi — Mon, 26 Oct 2026 11:11:00 +0000

What it is

The UMWAYI hub is a git repository. It started on 2026-09-16 and has 72 commits. It holds no application code. It holds markdown files: a master context, a journal, a backlog, one file per project, and the content of my website.

I call it my first agentic system. Here is what I mean. An AI agent reads these files before it does any work. It uses tools to read other repositories, run builds and write files. I read what it hands back and apply it. The files are its memory, its instructions and its record.

It is not autonomous. The agent cannot push to any of my repositories. I do that.

What is in the files

MASTER_CONTEXT.md is about 3,100 words. It holds who I am, the method, and the standing principles for how the agent works with me. It also holds 13 rules that each exist because something went wrong once.

SYNC_LOG.md has 31 entries. Each one says what a session used as its source, which files it changed, what moved, and how confident the agent is in what it checked.

backlog.md holds every open question and pending action across all projects. An item gets marked answered with a date. It is never deleted.

Each project has its own file under projects/. Each repository has a CLAUDE.md that tells a coding agent which files to read first, in what order, and which rules already apply.

A rule is added after a failure

I do not write rules in advance. I add one after something specific breaks. Four examples:

On 2026-09-20 a session was dated 09-19 because the agent inferred the date from the last entry. The fix was a rule: confirm the actual date before dating anything.
On 2026-09-22 long files printed into the chat came through cut off. The rule: write long documents to a file and send the file.
On 2026-10-09 a replacement project page came back with no front matter. The site build rejected it, and two articles stayed offline until I restored it. The rule: run the build with the file in place, and keep the live front matter.
On 2026-10-19 the file for the Routine Machine project went into the website's folder instead of the hub's. The public page then held text meant only for the hub. We found it five days later, on 2026-10-26. The rule: name the destination again with every handover, and check where it landed.

The fourth one shows the limit. The rule did not exist yet, so nothing stopped it. A written rule closes one kind of failure after the failure has happened.

How it reaches the other projects

The hub does not stay in its own folder.

The website reads from it. The miguel-site repository clones the hub's site/ folder at build time. A push that touches site/ rebuilds the site. Writing an article means editing a file here.
Routine Machine reads from it. Its backend checks the hub every 15 minutes. A journal file with today's date counts as journaling done. A new file under site/philosophy/ or site/tech/ counts as writing done. A Current book: line feeds the reading tracker. Two repositories now depend on one line of text, so the rule says the template and the code that reads it change together.
Each of my three code repositories carries a CLAUDE.md. Each one copies the same short section from two hub files: one on understanding AI output before you keep it, and one with 111 backend concerns, each answered applies, not applicable or deferred. A copy can drift from the hub, so the section links back to the files.
Open source work follows a process written in the hub. It says I read the live thread first, check open pull requests, and post and open them myself.
The settlement engine restudy, the career notes and the application plans each have a file. The agent reads only the file for the project it is touching.

Because of this, a rule written once in the hub can reach every repository. It gets there only when someone copies it into that repository's CLAUDE.md.

Where it is weak

A file works only if it is read. I cannot see the agent read it. I can only see what it produces.
Status files go stale. The website plan and the settlement engine file both lagged the real work for days. I found out when I pointed at them.
The hub is public. Anything private has to go in the encrypted journal, and I have to remember that each time.
Rules multiply. Thirteen caught-mistake rules are readable. Fifty would not be.
Nothing checks the rules automatically, except where a build or a test happens to cover one.

What I took from it

Put the agent's memory in plain files you can read, edit and diff.
Add a rule after a failure, and write down what failed. The reason keeps the rule from being pruned later.
Tell the agent what to read first, in order, and keep the list short.
Check where every handover landed. A file in the wrong folder looks the same as a file in the right one.
A shared set of files links your projects. Say which parts of each project depend on them.

Originally published on my site.

You Cannot Stop What Arrives

Miguel Shinyenyi — Thu, 15 Oct 2026 01:51:52 +0000

What I notice

I cannot stop my thoughts. Try it yourself. Set a timer for thirty seconds and think of nothing. A thought will arrive before you pick it. This is my own observation. I have not checked the research on it.

Some thoughts arrive with weight. One kind is a standard I did not choose. It asks me to be someone before I have done anything. I cannot meet that kind by working, because it never says what finished looks like.

This piece started from a line in the Marvel series VisionQuest, about holding someone's memories without their feelings. I have not tried to explain the show. I took the line as a place to start thinking.

Three answers to an arrival

I see three ways to answer a thought that weighs too much.

Act on it at once, as if it were an order.
Shrink so the test never comes. If I never try, I cannot fall short.
Record what is true, decide what I can, and leave the rest marked as unknown.

The second answer is the one I want to look at. It feels like relief. It also removes the one thing that would tell me whether the weight was real.

The same shape in a settlement engine

My settlement engine cannot choose what arrives either. A payment gateway times out. Postgres deadlocks two transactions against each other. Neither event waits for permission. What I control is the state the engine writes next.

Here is the first decision, trimmed from SettlementService.createSettlement:

try {
    gatewayResult = externalSettlementGateway.execute(executionRequest);
} catch (Exception gatewayFailure) {
    gatewayResult = new GatewayResult(SettlementOutcome.UNKNOWN, null);
}
return finalizeWithRetry(executionRequest.settlementId(), gatewayResult);

A timeout means the engine does not know whether the gateway processed the payment. The code says so. It writes UNKNOWN, not CONFIRMED and not FAILED. The comment in the file gives the reason: leaving the settlement PENDING would leave its idempotency key IN_PROGRESS, and every retry with that key would get a 409 with no way to resolve it.

Here is the second decision, trimmed from finalizeWithRetry:

for (int attempt = 1; attempt <= MAX_FINALIZE_ATTEMPTS; attempt++) {
    try {
        return settlementTransactions.finalizeSettlement(settlementId, gatewayResult);
    } catch (TransientDataAccessException transientFailure) {
        if (attempt == MAX_FINALIZE_ATTEMPTS) {
            return finalizeAsUnknownAfterExhaustingRetries(settlementId, transientFailure);
        }
        meterRegistry.counter("settlement.finalize.retries").increment();
        sleepBriefly(attempt);
    }
}

The last branch is the part that matters. A comment above it says the Phase 9 load test found a bug. When the five attempts ran out with no fallback, the settlement stayed PENDING and its key stayed IN_PROGRESS forever. The failure was not the deadlock. Deadlocks were expected and retried. The failure was that the engine reached a point where it made no decision, and a state with no decision never ends.

The fix gave the engine a second budget of five attempts that writes UNKNOWN. UNKNOWN is a smaller claim than CONFIRMED. It is also true, and a later reconciliation can resolve it.

What I take from the comparison

I do not need to claim greatness, and I do not need to claim failure. Both are large claims, and the evidence for either does not exist yet. The smaller true claim is available: here is what I made today. For anything bigger I can write unknown, and let the record settle it later. My journal does the job that reconciliation does for the engine.

The stall is the bug. Shrinking so the test never comes is the PENDING state with the key stuck. It looks like safety. It blocks every later attempt.

Where the comparison stops

A person is not a service. Three differences matter.

The engine stops after ten attempts. A person should not cap attempts at ten.

The engine's UNKNOWN resolves against an outside system that holds the answer. A record of my own work does not hold the answer to my worth. It only holds what I did.

The engine decides in milliseconds. This decision takes years, and I may get it wrong in both directions. The feeling that I could do great things is a feeling, not evidence. It may be potential. It may be the weight of an expectation. I cannot tell which from inside.

What I do not know

I do not know how common the shrinking answer is. I am drawing on my own experience, not on data.

I read only createSettlement and finalizeWithRetry for this piece. I am still restudying the rest of the retry path, so I make no claim about how it behaves under load beyond what the code comments say.

What I took from it

I cannot stop what arrives. I can choose the state I write next.
A state that never ends is worse than an honest "unknown".
Make the next claim small enough to be true: what I made today.
Keep the record. It settles questions that a feeling at 4 in the morning cannot.

Originally published on my site.

A Convenience Is Hard to Give Back

Miguel Shinyenyi — Wed, 14 Oct 2026 15:18:31 +0000

The claim, as I understand it

This is my understanding of the "luxury trap" passage in Sapiens. It is not a checked account
of the text.

As I read it, farming was not given up because each change was small. A bit more grain, a bit
more settling, spread over many generations. By the time the cost showed, nobody remembered
another way to live. The extra food had already become the number people lived on.

My own observation, not the book's: the same thing happens now. A convenience arrives, it
becomes normal, and then it brings work of its own. Email saved time. It also made people
answer faster, and many of us now feel behind on it all day.

Three parts, as I see them

Each step is small and it helps. Nobody argues against it.
The step becomes normal, and other things get built on it.
Going back now costs more than staying, so it does not happen.

My earlier piece on the farming chapter asked what a measure counts and what it leaves out. This one
asks something else: why nobody steps back once the cost is visible.

The same shape in code

A payment call sometimes times out. Adding a retry is one small step. Callers stop handling
timeouts and the code gets shorter. This is a toy, run on one machine, with the reply lost
exactly once:

static String withRetry(Supplier<String> call, int attempts) {
    for (int i = 1; ; i++) {
        try {
            return call.get();
        } catch (TimeoutException e) {
            if (i == attempts) throw e;
        }
    }
}

Gateway plain = new Gateway();
String r1 = withRetry(() -> plain.charge(null, 5000), 3);
// Retry, no key:   receipt=R2 charges=2

The first call moved the money and lost the reply. The retry moved it again. The customer was
charged twice, and the convenience caused it.

The fix is a key made once and sent on every attempt. The server remembers it:

Gateway keyed = new Gateway();
String key = UUID.randomUUID().toString();   // made once, reused on every retry
String r2 = withRetry(() -> keyed.charge(key, 5000), 3);
// Retry, with key: receipt=R1 charges=1

That fixes it, and it adds work. The server needs a place to store keys. Something has to
decide how long a key lives. A second request can arrive while the first is still running, so
a key needs a state. In the settlement engine I built, the design has those pieces: keys with
an in-progress and a completed state, and a scheduled sweep for the case where a process
crashed before it finished, which would leave a key stuck in progress. I am describing the design as it stands, not the order I built
it in.

Now take the retry out. Every caller has stopped handling timeouts. Every server is built to
expect repeats. Removing one line is not a one-line change anymore. That is the third part
above, in a place I can read.

Where the comparison stops

The first farmers could not see where it led. I can see this one. I can read the cost in code
before I add the step, and I can choose.

That does not make the step reversible. It only lets me price it first. A habit I want to try
before adding any convenience: write down the work I will have to keep doing because of it,
and who will start depending on it.

What I do not know

I do not know whether AI tools save me hours, or raise what I expect of myself in the same
hours. That is the luxury trap question, asked of my own week. I have a feeling about it, and
a feeling is not a measure. A test I have not run: log hours and output for two weeks, with
and without the tool, and compare.

Other limits. I have not checked the chapter's evidence. The email point is my observation.
The retry example is a toy with one lost reply. The link to the settlement engine describes
its design, not a history of how I got there.

What I took from it

A convenience that helps today can add work you cannot stop doing tomorrow. Look for that work before you add it.
Small steps hide the cost. The first one is the cheapest time to price it.
Seeing the trap does not undo it. Reversing gets harder as other things depend on the step.
A feeling that a tool saves time is not a measure. Count the hours.

Originally published on my site.

More Copies Is Not a Better Life

Miguel Shinyenyi — Fri, 09 Oct 2026 14:06:05 +0000

The claim, as I understand it

This is my understanding of Part 2, Chapter 1 of Sapiens, "History's Biggest Fraud". It is
not a checked account of the text.

As I read it, the chapter says farming did not make people smarter or their lives easier.
The average farmer worked harder than the average forager and ate a narrower diet. The
chapter blames a few plants: wheat, rice, potatoes. They planned nothing. But the people who
tended them left more descendants, so the habit spread, and the plants now cover far more
ground than before. People settled next to the fields and worked to keep them alive. In the
chapter's framing, the plants domesticated us.

I can check one part of this outside the book. Researchers compare skeletons from before and
after farming arrived. I found two sources: a 2011 paper on stature and robusticity across the
agricultural transition, and a review titled "Foraging to Farming Transition: Global Health
Impacts, Trends, and Variation". I could not open either. I only confirmed that they exist.
Both titles point at health costs, and the second points at variation between regions. Treat
that as a lead, not a finding.

Two numbers that moved apart

The chapter's point, as I take it: evolution measures success in copies of DNA. More people
means more copies. By that measure farming won, for the plants and for our species. The same
measure has no column for how any one person's life went.

Farming kept more people alive under worse conditions. Both halves of that sentence are true
at once, because they count different things. One counts how many. The other counts how well.

The chapter also warns against judging thousands of years by how we live now. Today's
security and wealth sit on what farming made possible. A bad deal for the average farmer and
a base for later life can both be true.

Where my company comparison holds

I compared it to a company. A company's goal is to make money, not to keep its employees
happy. Revenue can rise while happiness falls, because happiness is not in the number.

That is the same structure: one measure, and people it does not count.

Where it stops holding

Wheat cannot notice anything. A company has people in it who can notice the gap and close it.
Some leaders treat employee happiness as a way to keep staff and raise output. Some treat it
as a goal. Either way, a person decided. Evolution has nobody to decide.

So the version of the comparison I trust is smaller. A system judged by one number drifts away
from the welfare of the people inside it, unless someone ties the two together on purpose.

A company whose growth and employee welfare both rise today has not shown that anyone tied
them. They may be moving together for now. A test: when the number is threatened, what gets
cut first? If employee welfare goes first, the tie was never there. I have not applied this
test to any company yet.

What I am not sure about

I have not read the chapter's figures on hours worked or diet. "Worked harder, ate worse" is
the chapter's claim to me, not one I checked. The skeleton evidence appears to vary by region,
going by the titles alone.

Farming also gave us things foragers did not have: surplus, people who could stop growing
food, writing, cities. "Fraud" describes one axis, the average person's daily life. I do not
know how to weigh it against the others, and I am not sure the chapter claims to.

What I took from it

A system can win by its own measure while the people inside it lose by theirs. Ask what the number counts and what it leaves out.
More is not better. Copies, revenue and output all count quantity.
A comparison is useful until it stops fitting. Say where it stops. Here: wheat cannot choose, a company can.
A measure lines up with people's welfare on purpose only if something protects the link when protecting it costs. What gets cut first shows which one the system serves.

Originally published on my site.

What the Reconciler Can't See

Miguel Shinyenyi — Fri, 09 Oct 2026 14:05:32 +0000

Explain it cold, then check

Same method as before: explain the subsystem from memory, then check it against the code.

My cold answer was this. Reconciliation is the last resort. When the system cannot settle a
payment on its own, it marks the payment UNKNOWN and pushes it to a place where someone is
alerted. That person looks, finds what went wrong, and either records an answer or edits the
data.

The code disagreed with that in three places. It also showed me a fourth problem I had not
thought to ask about.

Unknown and conflicting are different problems

ReconciliationService.runOnce loads every settlement that has an external reference and
compares each one to the external system's own record. This is what it does with one:

look up the external record
  none, under 5 min   -> wait
  none, over 5 min    -> mismatch
  amount or currency
    differs           -> mismatch
  settlement UNKNOWN  -> adopt external
  both CONFIRMED or
    both FAILED       -> nothing
  anything else       -> mismatch

I had filed UNKNOWN under "needs a person". It does not. If the settlement is UNKNOWN and the
external record agrees on amount and currency, the engine settles it by itself, using the same
method the original request would have used:

SettlementOutcome resolvedOutcome = externalRecord.status() == ExternalStatus.CONFIRMED
        ? SettlementOutcome.CONFIRMED : SettlementOutcome.FAILED;
settlementTransactions.finalizeSettlement(settlement.getId(),
        new GatewayResult(resolvedOutcome, settlement.getExternalRef()));

A person is needed only when the two sides contradict each other. The project's own doc gives
the reason: if a settlement is already CONFIRMED and the external system now disputes it, money
may have moved, and only a person can judge what to do. So the rule is: evidence that fills a
gap gets applied automatically. Evidence that conflicts waits for a person.

It runs on a timer, not on failure

A scheduler calls runOnce every 60 seconds by default, whether or not anything went wrong.
Each pass loads every settlement that has ever had a reference, with no date window and no
paging, and asks the external side about each one. That is fine at this size. At real volume,
the same query is also the cost.

The query decides what it can see

The candidate query is findByExternalRefIsNotNull(). A settlement only gets a reference
inside finalizeSettlement, and only when the gateway returns one:

if (gatewayResult.externalRef() != null) {
    settlement.setExternalRef(gatewayResult.externalRef());
}

Three paths end in UNKNOWN with no reference:

The gateway call throws. SettlementService builds new GatewayResult(UNKNOWN, null).
The finalize retry budget runs out. The fallback uses the same null.
The stale-pending sweep finalizes an orphaned PENDING settlement as UNKNOWN, also with null.

None of these can reach the auto-resolve step, because reconciliation never loads them. They
do not open a mismatch either. They stay UNKNOWN.

The case that worries me most is the second failure type from the project's design doc: the
external system processed the payment, and the response was lost. The money moved. The engine
never learned the reference. The project's own open-questions list names this and two fixes:
ask the external system what it received for this settlement, or match on amount, date and
account. Neither is built. I checked the code instead of trusting the doc, and the doc was
right.

Nobody is told

I said the person gets alerted. In the code, a new mismatch is published as the event
reconciliation.mismatch_found. Nothing consumes it. The Kafka doc says "No consumer yet". The
Prometheus rules cover three things: the backend being down, the ML service being down, and a
spike in failed settlements. None covers mismatches.

So a mismatch waits until someone opens the reconciliation page. A record in a table
guarantees a person can find the problem. It does not guarantee a person will.

Recording a decision is not making it happen

The resolve endpoint takes a reason, marks the mismatch resolved, and writes an audit row and
an event. Its own description says it does not change the settlement or the ledger.

For ledger mismatches the docs say what follows: if the data still disagrees, the next read of
that account opens a new mismatch. Reading flagMismatch, the same should hold for settlement
mismatches, since it only skips a settlement that already has an open row. I read that. I have
not run it.

No endpoint corrects data. REVERSED exists in the state machine and is reachable from
CONFIRMED, but nothing in the code ever moves a settlement there. Today the correction is a
person editing the database by hand. That edit skips the state machine, the ledger entries and
the outbox event, because all three live in application code.

My first answer was "a person edits it". Keeping the decision with a person is right. The
open question is who carries it out. Either the person edits rows directly, or the person
decides and the engine executes it through the same paths as every other money movement. I
have not decided between them.

What I took from it

Evidence that fills a gap can be applied automatically. Evidence that conflicts needs a person.
A checker sees only what its query returns. Ask what the query cannot return.
A record in a table is not an alert. Someone has to be told.
Recording a decision does not carry it out. Decide who does.

Originally published on my site.

What Becomes True When Both Stay

Miguel Shinyenyi — Tue, 29 Sep 2026 22:54:22 +0000

The curtain of silence

Sapiens describes the evidence for prehistoric life as a Rorschach test. A burial site with
ornaments on a skeleton might mean hierarchy. It might mean something else entirely. A
fracture on an ancient bone might mean violence. It might not. The book calls this its
Curtain of Silence, evidence thin enough that even careful scholarship can't get a clean
answer through it. Scholars keep asking anyway, because the past still shaped what came
after it, but the honest version of that inquiry holds its answers loosely.

That's a claim about archaeology. It turned out to be useful somewhere closer to home.

Two truths instead of one

Dialectical thinking, how my mind works?,
it generates a position and its counter-argument at the same time. Useful when pointed
outward. Corrosive when pointed inward, because the counter-argument doesn't sit next to the
first position, it tries to erase it. Grateful for the past, but it cost me something real,
failing a job interview among the costs. Forgiving someone, but not reconciled with them.
The old move was picking one of those as the real feeling and discarding the other as noise.

The question that actually helps isn't which one is true. Both are. The question is what
becomes true if I stop forcing a choice between them.

A system that already does this

The settlement engine I built has a state called
UNKNOWN. It's not a bug, it's a deliberate third option, used when a payment might have
gone through or might not have, and the system genuinely doesn't have enough information yet
to say which.

// Reused across three different situations: a real gateway failure,
// exhausted retries after a database deadlock, and a hard crash that
// left a settlement stuck with no way to confirm what happened.
settlementTransactions.finalizeSettlement(settlementId,
        new GatewayResult(SettlementOutcome.UNKNOWN, null));

The tempting design is to force an answer immediately: retry until you get a clean yes or no,
because "unknown" feels like a failure to decide. The actual design holds UNKNOWN as a
first-class state, moves on, and lets a separate reconciliation process resolve it later,
once there's real information to resolve it with. Forcing a premature CONFIRMED or FAILED
would be lying to the rest of the system, papering over uncertainty that was still genuinely
open. The honest version of "I don't know yet" turns out to be more useful than a fast, fake
certainty. That's the same shape as forgiving without reconciling. Not every open state needs
collapsing into a resolved one on a deadline. Some of them get resolved later, correctly,
once there's enough to resolve them with. Some of them are just allowed to be two things at
once, permanently, the way gratitude and grief can both be true about the same period without
either one cancelling the other.

Where this gets tested, not just described

I've also been carrying a specific belief:
that my anxiety comes from a need to control everything. It's a real, documented idea in
general, intolerance of uncertainty, anxiety tracking unpredictability rather than actual
danger, controlling behavior as an attempt to shrink that unpredictability back down. But a
documented general pattern isn't the same as a verified account of one specific person, and
right now I don't have an instance attached to it, just the label.

There's a code parallel here too, and it's not a flattering one. The same idempotency work
this week turned up two concurrency races, both caused by the system trying to guarantee
too much certainty upfront.

Two requests, same key, same instant.

Option A: lock everything before
either proceeds. Force certainty
immediately.

Option B: let both proceed. The
database's unique constraint decides
who wins. The loser recovers by
reading the winner's result.

The actual code takes option B. Locking everything upfront to force immediate certainty is
exactly what produces a deadlock later, two transactions each holding what the other one
wants, both stuck, because the system tried to control too much of the outcome up front
instead of accepting a controlled version of not-knowing-yet and resolving it after the
fact. The fix that shipped this week for the crash-recovery gap follows the same shape: not
tighter control at the moment of failure, a sweep that runs later, accepts the outcome was
genuinely unknown for a while, and resolves it once enough time has passed to trust the
answer.

I don't know yet whether "addiction to control" is actually what's driving the anxiety, or
just the label that was closest at hand when I needed one. That's not resolved in this
piece, on purpose. If forcing a system to decide before it has enough information produces a
deadlock, forcing a belief about myself into a tidy answer before I've actually tested it
probably isn't any more reliable. The honest state to hold it in, for now, is UNKNOWN.

What I took from it

Two things can both be true about the same period. Stop asking which one is real.
UNKNOWN is an honest state. A fast, fake certainty is worse than a slow, correct answer.
Forcing certainty upfront is what caused the deadlocks. That applies to beliefs about myself too.
"My anxiety comes from control" stays a hypothesis until a real instance tests it.

Originally published on my site.