# John Wainaina Karanja: architecture reviews

> John Wainaina Karanja (also known as @qwainaina, which reads "cue Wainaina") is a product and systems lead who works remotely in UTC+3. He reviews one software system for a fixed price. He tells you what works, what could break and what to fix first. His areas: payments and ledgers, AI at work, technical leadership and handover, technical due diligence, and hands-on team training on AI coding agents. Contact: info@johnkaranja.com. Request a review: https://johnkaranja.com/book/request/

This file holds the full text of the published pages, generated from the site itself. Prices are in US dollars. The samples are fictional and labelled as such.


# The book
Source: https://johnkaranja.com/book/

## Page: https://johnkaranja.com/book/
## Know what to fix in your system before you build further.
[For the Money (payments and ledgers) edition]
This copy opens at: money moving through a product
[For the AI at work edition]
This copy opens at: AI doing real work
[For the Technical lead edition]
This copy opens at: a technical lead you can trust
[For the Investor (due diligence) edition]
This copy opens at: investing in or buying a product
[For the Team training edition]
This copy opens at: a team learning AI agents
A short book for founders, teams and investors: products that move money or put AI to work, and the technical lead, the due diligence or the training that goes with them.
by John Wainaina Karanja · building software since 2007 · UTC+3
@qwainaina reads “cue Wainaina”: my middle name, written as music.
[Read the book](https://johnkaranja.com/book/contents/) [The short version (30 seconds)](https://johnkaranja.com/book/short/)
[Free inside: 16 rules for systems people trust](https://johnkaranja.com/book/rules/)

## Page: https://johnkaranja.com/book/contents/
Contents
### Fourteen pages. Read it all, or jump.
- [The short version the whole pitch in 30 seconds](https://johnkaranja.com/book/short/)
- [Before we begin · the author who I am, and the public record](https://johnkaranja.com/book/author/)
- [Chapter one · five questions a one-minute self-check, and your reading](https://johnkaranja.com/book/questions/)
- [Chapter two · a sample review what you would receive](https://johnkaranja.com/book/sample/)
- [Chapter three · the rules behind it 16 rules for systems people trust](https://johnkaranja.com/book/rules/)
- [Chapter four · the work products I built and run](https://johnkaranja.com/book/work/)
- [Chapter five · how it runs, and the offer scope, access, price and the 60-day credit](https://johnkaranja.com/book/how/)
- [The last page · your request five short answers](https://johnkaranja.com/book/request/)
Your edition
#### Which is closest to your work?
The questions, the sample and the offer follow your choice. You can change it here at any time.
Money moves through my product Payments, payouts, wallets, ledgers or reconciliation.
I want AI doing real work in my business Agents and automation people will rely on.
I need a technical lead I can trust A product that needs a steady, accountable hand.
I'm deciding whether to invest in or buy a product Technical due diligence before you sign.
My team needs to learn this Hands-on training on AI coding agents and workflows.
General Any system, or none of these.

## Page: https://johnkaranja.com/book/short/
The short version · 30 seconds
### The whole book on one spread.
I'm John Wainaina Karanja, a product and systems lead. I work remotely, in UTC+3. I design the systems a business runs on, and I lead the build.
**What I do:**
I review one system for a fixed price. You learn what works, what could break, and what to fix first. If you want, I then lead the work.
**For whom:**
Founders whose product moves money or puts AI to work; anyone who needs a steady technical lead; investors before they sign; teams learning to build with AI agents.
**Proof:**
Products I built and run: Melanin, Nyukia and Space.ke. Opening keynote at the World Blockchain Summit Nairobi, 2018.
**Free inside:**
16 rules for systems people trust, each with three questions for your team. [Read the rules](https://johnkaranja.com/book/rules/)
**How it runs:**
A fixed price, and about 10 to 15 days for a review. I only need read-only access. You get a written report and a call to go through it. Hire me for the fixes within 60 days and the fee counts towards them.
[Request a review](https://johnkaranja.com/book/request/) [Read the whole book](https://johnkaranja.com/book/author/)

## Page: https://johnkaranja.com/book/author/
John Wainaina Karanja · UTC+3
Before we begin · the author
### I design the systems a business runs on, and lead their delivery.
- 2007 Founded Space Kenya Networks, a software and web services company.
- 2016 Founded BitHub Africa, a blockchain accelerator in Nairobi; trained teams, advised founders and spoke at industry events.
- Now I build and run my own products in payments, mining, language and research. They are in chapter four.
- Alias @qwainaina, read as “cue Wainaina”. A cue is a musician's signal to start playing. My logo is my middle name, written as music.
- Study Master's, University of Oxford. Bachelor's, Strathmore University.
#### Public record
- [The journey so far](https://www.howwemadeitinafrica.com/the-journey-so-far-john-wainaina-karanja-founder-bithub-africa/) How We Made It In Africa
- [Opening keynote, World Blockchain Summit Nairobi, 2018](https://ibtimes.co.in/world-blockchain-summit-nairobi-tops-all-twitter-trends-africa-764771) International Business Times
- [Blockchain in Silicon Savannah](https://www.lombardodier.com/contents/corporate-news/ft-rethink/november/the-blockchain-revolution-in-the.html) FT Rethink film, 2018
- [Inside Kenya's blockchain ecosystem](https://nation.africa/kenya/business/inside-kenya-s-blockchain-ecosystem-what-the-future-holds-248804) Daily Nation
Reviews are a new offer. The sample in chapter two shows exactly what you get.

## Page: https://johnkaranja.com/book/questions/
Chapter one · five questions
### Five questions before you build further.
It takes a minute. Answer as things are today; "not sure" is an honest answer.
Nothing is stored or sent. Your answers stay on this page unless you choose to send them.
[For the General edition]
- For each important fact, is there one record that counts? (weak spot: Two sources of truth. Why it matters: When two records can disagree, every figure built on them is in doubt. Choose the one that counts.)
- Can you release a small change and undo it the same day? (weak spot: Risky releases. Why it matters: A change you cannot undo the same day makes every release a gamble. Prefer small, reversible steps.)
- If a request times out, does the system know whether it happened? (weak spot: Uncertain outcomes. Why it matters: A timeout is not a failure. If the system does not record what happened, a retry can do the work twice.)
- Do tests decide when a piece of work is done? (weak spot: Done by opinion. Why it matters: Without agreed checks, "finished" is only an opinion, and things that break go unnoticed.)
- Could a new developer explain the main flow from one diagram? (weak spot: No map. Why it matters: If the main flow lives only in people's heads, every decision about it is slower and riskier.)
[For the Money (payments and ledgers) edition]
- If the connection drops mid-payout, can you tell whether the payment went out? (weak spot: Uncertain payouts. Why it matters: If you do not know whether a payout went out, check it against the record before you try again.)
- Is each payout written into your records before it is sent? (weak spot: Double sends. Why it matters: If nothing is written down before sending, a retry can pay the same request twice.)
- Do you confirm an incoming payment at its source, not from the browser? (weak spot: A trusted browser. Why it matters: A payment the browser reports is easy to fake. Confirm it at the source before granting access.)
- Can you match every balance you show to its source? (weak spot: Unreconciled balances. Why it matters: If you cannot trace a balance back to the bank, ledger or chain, you cannot defend it when someone asks.)
- If the same statement or event arrives twice, is the second one refused? (weak spot: Double counting. Why it matters: If the same statement or event can be recorded twice, totals go wrong while the books still balance.)
[For the AI at work edition]
- Does it only read and act on sources you have approved? (weak spot: Open sources. Why it matters: An AI that can draw on anything will sooner or later act on something you never approved.)
- Do you have test cases with known good outcomes? (weak spot: No yardstick. Why it matters: Without test cases and known good outcomes, nobody can say whether a change made it better or worse.)
- When it is unsure, does a person decide? (weak spot: No human fallback. Why it matters: An unsure result delivered with confidence is worse than a handover to a person.)
- Can you see which source or step each output came from? (weak spot: Untraceable outputs. Why it matters: If you cannot see where an output came from, you cannot correct the source or explain the mistake.)
- Is there a written list of what it must never do? (weak spot: No boundaries. Why it matters: A system with no written limits will be tested by its users first.)
[For the Technical lead edition]
- Could someone outside your team explain how the product is built from what is written down? (weak spot: Knowledge in heads. Why it matters: If how the product works is not written down, every new person and every decision starts from guesswork.)
- If your main developer left tomorrow, could someone else ship a change next week? (weak spot: Single point of failure. Why it matters: When one person holds the keys and the knowledge, their absence stops the product.)
- Do you know which part of the system would break first if usage doubled? (weak spot: Unknown limits. Why it matters: Not knowing what breaks first under load means finding out from your customers.)
- Is one person accountable for technical decisions, with time to make them? (weak spot: No owner. Why it matters: Technical decisions without a named, accountable owner drift, or get made by default.)
- Do releases follow a checklist, with a way back if something breaks? (weak spot: Risky releases. Why it matters: A release with no checklist and no way back turns every change into a gamble.)
[For the Investor (due diligence) edition]
- Have you seen the product's code and infrastructure, not just a demo? (weak spot: Demo-only view. Why it matters: A demo shows what works today. The code and the infrastructure show what it will cost to keep working.)
- Do you know who owns the code, the cloud accounts and the domains? (weak spot: Unclear ownership. Why it matters: If the code, accounts or domains belong to someone else, you may be buying a licence, not a product.)
- Could the product keep running and changing if its founding developer left? (weak spot: Key-person risk. Why it matters: A product that only its founding developer can change carries that person's risk into the deal.)
- Do you know what the product costs to run each month, and why? (weak spot: Unknown running cost. Why it matters: A running cost nobody can explain usually grows after the deal, not before.)
- Has anyone checked the pitch's technical claims against the system itself? (weak spot: Unchecked claims. Why it matters: A claim in a pitch is a hypothesis until someone checks it against the system.)
[For the Team training edition]
- Does your team use AI coding agents with agreed rules for what they may change? (weak spot: No rules for agents. Why it matters: AI coding agents with no agreed rules change things nobody asked them to.)
- Are agent-written changes reviewed with the same checks as human ones? (weak spot: Unreviewed changes. Why it matters: Agent-written code that skips the usual checks is where regressions hide.)
- Does your team share prompts, rules and lessons, rather than each person working alone? (weak spot: Lessons not shared. Why it matters: When each developer learns alone, the team pays for the same mistakes several times.)
- Can your team explain how its own agent workflows decide and act? (weak spot: Opaque workflows. Why it matters: A workflow nobody can explain cannot be trusted, fixed or improved.)
- Has anyone on the team built and shipped one agent workflow end to end? (weak spot: No hands-on experience. Why it matters: Reading about agents is not the same as shipping one; the first build teaches most.)

## Page: https://johnkaranja.com/book/reading/
Chapter one · your reading
### Your reading
Answer the five questions first; your reading appears here.
This is a self-check, not a finding. A review checks each answer against evidence.
[See a sample review](https://johnkaranja.com/book/sample/) [Send these answers with a request](https://johnkaranja.com/book/request/)
[Go to the questions](https://johnkaranja.com/book/questions/)

## Page: https://johnkaranja.com/book/sample/
Chapter two · a sample review
### What you would receive
Illustrative sample · a fictional system, not a client's
Every review starts with a map of the system as it is today. Numbered pins show where the risks are. The next page explains each pin and what to do.
A real review runs to several pages. The full sample is linked on the next page, to read or download.
[For the Money (payments and ledgers) edition]
Payment-state map: a rewards app that pays out in cryptocurrency
- Player answers
- Score service keeps its own balance
- Reward claim
- Payout sender sends before it claims
- The chain timeouts retried blind
[For the AI at work edition]
Workflow and control map: an agent that drafts supplier payments from emailed invoices
- Shared inbox reads every sender
- Invoice reader
- Draft payment no test cases
- Approval approver sees only the total
- Ledger
[For the General, Technical lead edition]
Current-state diagram: a marketplace built quickly with AI help, now with paying users
- Web app
- API deployed by hand
- Database restore never tested
- Payments provider
- One laptop holds every key
[For the Investor (due diligence) edition]
Evidence map: a small software business before an acquisition
- Seller's deck claims "real-time"
- Code repository owned by a former contractor
- Hosting accounts
- Customer data restore never tested
- Handover
[For the Team training edition]
Workshop outline: AI coding agents in a five-person team, one day
- How agents fail
- One workflow, hands-on built together
- Rules and review gates written for your repo
- Your own codebase
- Next month's plan who does what

## Page: https://johnkaranja.com/book/findings/
Chapter two · findings and brief
### Each pin, explained
[For the Money (payments and ledgers) edition]
#### A payout can be sent twice High
Evidence: the sender retries after a timeout, and nothing records that the request was already sent.
Change: write each request down before sending. A retry checks that record first. [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
#### A timed-out payout has no owner High
Evidence: timeouts are logged, with no state a person can review.
Change: mark it "uncertain" and check the chain before any retry. [Rule 10: Expect other services to fail](https://johnkaranja.com/guide/expect-failure/)
#### Two records hold one balance Medium
Evidence: the score service and the payout table each keep a total. Unknown: how often they have differed.
Change: choose one record that counts, and work the other out from it. [Rule 01: Keep each fact in one place](https://johnkaranja.com/guide/one-source-of-truth/)
[For the AI at work edition]
#### The agent acts on mail it should not trust High
Evidence: invoices from any sender are read and drafted, including first-time senders.
Change: act only on approved suppliers, and match every invoice to a purchase order. [Rule 13: Keep AI on a budget and on the facts](https://johnkaranja.com/guide/ai-on-a-budget/)
#### Nobody can say whether a change helped High
Evidence: there is no set of past invoices with known correct drafts.
Change: keep 30 past invoices as a test set and run it before each change. [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
#### Approval is a rubber stamp Medium
Evidence: the approver sees the amount, not the source invoice or what the agent changed. Unknown: how many drafts were approved unread.
Change: show the source document and the agent's reasoning beside every approval. [Rule 09: Several simple guards beat one clever wall](https://johnkaranja.com/guide/layers-of-protection/)
[For the General, Technical lead edition]
#### One person holds every key High
Evidence: production access, deploy rights and the domain account sit with one developer.
Change: a list of who has access to what, a second owner on every account, and automatic releases. [Rule 07: Give each part only the power it needs](https://johnkaranja.com/guide/least-power/)
#### No way back from a bad release High
Evidence: changes are copied to the server by hand; there is no previous version to return to.
Change: automatic releases that can go back to the last version in one step. [Rule 15: Ship only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
#### The backups have never been restored Medium
Evidence: nightly backups exist. Unknown: whether one has ever been restored, and how long it takes.
Change: a timed restore test, repeated monthly. [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
[For the Investor (due diligence) edition]
#### The code belongs to someone else High
Evidence: the repository and the cloud account are registered to a former contractor.
Change: make the transfer of both a condition of signing. [Rule 07: Give each part only the power it needs](https://johnkaranja.com/guide/least-power/)
#### "Real-time" is a nightly batch High
Evidence: the sync job runs once a day; the deck says real-time.
Change: correct the assumption in the valuation, or require the fix before closing. [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
#### Customer data has never been restored Medium
Evidence: backups run nightly. Unknown: whether a restore works, and how long it takes.
Change: a witnessed restore test before signing. [Rule 15: Ship only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
[For the Team training edition]
#### A shared rule file for your agents
What: written together during the day, for your own repository.
You leave with: what agents may change, what they must ask about, and what they must never touch. [Rule 13: Keep AI on a budget and on the facts](https://johnkaranja.com/guide/ai-on-a-budget/)
#### One working workflow
What: built end to end by the team on a real task.
You leave with: a pattern the team can copy for the next task. [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
#### A review gate
What: agent-written changes pass the same checks as human ones. Unknown: which checks your pipeline already runs.
You leave with: a pull-request checklist for agent work. [Rule 15: Ship only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
[For the Money (payments and ledgers) edition]
#### What to do first
- Write a record with a unique number for each request.
- The sender refuses any request without that record.
- Done when: a forced timeout never sends twice.
[For the AI at work edition]
#### What to do first
- Add an approved-supplier list and purchase-order matching.
- Build the 30-invoice test set and record today's results.
- Done when: an invoice from an unknown sender is never drafted.
[For the General, Technical lead edition]
#### First 30 days · the plan
- Week one: a list of who has access, and a second owner on every account.
- Weeks two and three: automatic releases you can undo in one step.
- Done when: last night's backup is restored, timed and written down.
[For the Investor (due diligence) edition]
#### Conditions before signing
- Ownership of code, accounts and domains transferred at signing.
- A witnessed restore of customer data.
- The "real-time" claim corrected in the sale documents.
[For the Team training edition]
#### The day · at a glance
- Morning: how agents fail, and one workflow built together.
- Afternoon: rules and review gates on your own codebase.
- Afterwards: a one-page plan for the next month.
Findings keep what the evidence shows apart from what is still unknown. The plan is written so your own team, or any other, can act on it.
[For the Money (payments and ledgers) edition]
[Read the full sample report](https://johnkaranja.com/samples/pay/) · [PDF](https://johnkaranja.com/samples/pay.pdf)
[For the AI at work edition]
[Read the full sample report](https://johnkaranja.com/samples/ai/) · [PDF](https://johnkaranja.com/samples/ai.pdf)
[For the General, Technical lead edition]
[Read the full sample report](https://johnkaranja.com/samples/lead/) · [PDF](https://johnkaranja.com/samples/lead.pdf)
[For the Investor (due diligence) edition]
[Read the full sample report](https://johnkaranja.com/samples/invest/) · [PDF](https://johnkaranja.com/samples/invest.pdf)
[For the Team training edition]
[Read the full sample workshop pack](https://johnkaranja.com/samples/team/) · [PDF](https://johnkaranja.com/samples/team.pdf)
[How a review runs](https://johnkaranja.com/book/how/) [Request a review](https://johnkaranja.com/book/request/)

## Page: https://johnkaranja.com/book/rules/
Chapter three · the rules behind it
### 16 rules for systems people trust
These are the rules I build by. In a review, every finding names the rule it breaks. Choose a cell to read one.
[All 16 rules as full pages](https://johnkaranja.com/guide/)
Rule 01 of 16
#### Keep each fact in one place
Decide where each important fact lives, and let everything else read it from there.
Without it: A customer's balance shows one figure in the app and another in the payout table. Support cannot answer, and the books cannot be trusted.
Ask your team
- For each important fact, can you name the one record that counts?
- If two records disagree, does anything warn you?
- Could a new developer find where a price or a balance is stored within an hour?
[Read the full rule](https://johnkaranja.com/guide/one-source-of-truth/) [Request a review](https://johnkaranja.com/book/request/)

## Page: https://johnkaranja.com/book/work/
Chapter four · the work
### What I have built
I'm John Wainaina Karanja, a product and systems lead. I design, lead and deliver. If a specialist is needed, we agree that first.
Three products by name. The systems behind my other work, by what they do. The honey is the benefit I aim for, not a promise.
What I don't do: I don't write or audit smart contracts, train AI models from scratch, or give investment advice. I plan around them and work with the specialists who do.
Energy and Bitcoin mining
#### [Melanin](https://melanin.solar)
Turns spare electricity into Bitcoin mining: a mining pool, and [Melanin Click](https://melanin.click), an app that mines to your own wallet from a computer, a Raspberry Pi board or a phone.
Honey Power that would be wasted becomes value, with rewards people can inspect.
- Device
- Pool
- Counting each miner's work
- Building the block
- Payout
Trivia and rewards
#### [Nyukia](https://nyukia.com)
A Bitcoin trivia game with scoring, leaderboards and cryptocurrency reward payouts.
Honey Learning that connects game progress with a traceable reward process.
- Answer
- Score
- Claim the reward
- Send the payout
- Reconcile
Property · advisory
#### [Space.ke](https://space.ke)
Verified video tours of Kenyan property before you enquire. An assistant answers only from the site, and passes you to a person when needed.
Honey Buyers find relevant answers and reach a person when a question needs judgement.
- Site content
- An assistant that answers from the site
- Answer checks
- A person takes over
System · on-chain intelligence
#### Chain intelligence service
Tracks wallet and token activity on a public blockchain, explains what large holders do, and sends alerts. Paid plans open only after the payment is confirmed on the chain.
Honey Public data made readable, with payment treated as its own control.
- Chain data
- Chain reader
- Analysis
- Payment check
- Research view
System · AI agents
#### Agent operations system
Scheduled AI agents that do real office work: they read mail and records, draft replies and reports, keep a record of decisions and tasks, and raise only urgent alerts. A person approves anything that leaves.
Honey Routine work done every day, with people deciding what matters.
- Sources
- Agents
- Drafts
- Human approval
- Action
System · finance automation
#### Finance back-office
Reads bank and mobile-money statements into the books of several companies, checks they match, links every figure to its source, and tracks filing deadlines.
Honey Books you can trace, and deadlines you see coming.
- Bank statements
- Double-entry ledger
- Reconciliation checks
- Human review
System · protocol
#### Mining protocol
A digital currency anyone can mine on an ordinary computer: its own chain, wallets and mining software, and a reward token other products pay out in.
Honey An open way in for people without mining hardware.
System · education and voice
#### Voice-first language tutor
Speech practice for an African language, with spaced practice and answers from checked sources. Draft material stays apart from approved lessons.
Honey Practice material that stays connected to its sources and review status.
- Candidate material
- Linguistic review
- Admitted content
- Speech practice
System · research
#### Research framework
Scores new technologies on several measures, records where each fact came from, and compares signs with history before a decision.
Honey Assumptions and evidence that are easier to inspect.

## Page: https://johnkaranja.com/book/how/
Chapter five · how a review runs
### How a review runs
- You tell me what the system does and the decision you need to make.
- We agree the scope, the materials and the dates in writing. Nothing starts before that.
- You give read-only access, or a sample with private details removed. The days start when access works.
- I review, then send the written report.
- We go through it on a call, and I answer one round of follow-up questions.
#### Access and confidentiality
I only need read-only access. Never send passwords or live keys. I sign your confidentiality agreement, or you can use mine. I delete your materials on a date we agree.
#### If I find little wrong
Then the report says so, with the evidence. Proof that a system is sound is useful, to you and to anyone you show it to.
#### Who does the work
I do the review myself. Nothing is handed to a junior.

## Page: https://johnkaranja.com/book/offer/
Chapter five · the offer
[For the General edition]
### Architecture review
USD 2,450 Fixed · 10 hours at USD 245 an hour · ready in about 10 days
Find out where your system is sound, where it is fragile and what to change first. One application, the most important thing your users do in it, and the services it connects to.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A 90-minute working session on one question, USD 300, which counts towards the review.
Go further If you want help building it: the work in reviewable phases, quoted after the review.
[For the Money (payments and ledgers) edition]
### Payments and ledger integrity check
USD 2,450 Fixed · 10 hours at USD 245 an hour · ready in about 14 days
Find where a payment could be lost, repeated or recorded wrongly. One payment or payout flow and its ledger trail, traced with a sample that has private details removed. No live payments.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A 90-minute working session on one flow, USD 300, which counts towards the check.
Go further Then the fix phase, and monthly reconciliation support if you want it, quoted after the check.
[For the AI at work edition]
### AI readiness review
USD 2,450 Fixed · 10 hours at USD 245 an hour · ready in about 10 days
Find out if an AI workflow is ready for a small, limited trial, what to prove first, and how people stay in control when it goes wrong.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A fixed setup audit of one workflow you already run, USD 1,000.
Go further Then a trial build, and monthly help from USD 5,000 a month (about ten hours a week) if you want it.
[For the Technical lead edition]
### Architecture review or handover check
USD 2,450 Fixed · 10 hours at USD 245 an hour · ready in about 10 days
Before you hand me, or anyone, the keys: a clear account of how the product is built, who holds what, what breaks first, and a plan for the first 30 days.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A 90-minute working session on the decision in front of you, USD 300, which counts towards the review.
Go further Then a part-time technical lead: from USD 5,000 a month, about ten hours a week.
[For the Investor (due diligence) edition]
### Technical due diligence
USD 4,500 Fixed · a product with 1 to 2 developers · about 15 days
A clear account of the technical risks, open questions and handover difficulties before you buy, invest in or partner with a product. Larger codebases are quoted separately.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A 90-minute working session on the deal in front of you, USD 300, which counts towards the diligence.
Go further After the deal: a technical plan for the first 90 days, quoted separately.
[For the Team training edition]
### One-day hands-on workshop
USD 2,000 Fixed · one day, up to 10 people, online or on site
Your team builds one AI-agent workflow end to end on its own codebase, and leaves with rules, a review gate and a plan.
Hire me for the follow-on work within 60 days and the full fee counts towards it.
Start smaller A 90-minute briefing for leaders, USD 300, which counts towards the workshop.
Go further Then 4 to 12 weeks of coaching for the team, quoted per team.
[For the General edition]
#### You get
- A labelled diagram of the system as it is
- Findings, most important first, with evidence and what is still unknown
- A recommended design, with its pros and cons
- A short plan, in order, your team can act on
- A call to go through it, and one round of questions
Not included: code changes, deployment, load or penetration testing, security certification.
Checked against rules [01](https://johnkaranja.com/guide/one-source-of-truth/), [03](https://johnkaranja.com/guide/choose-how-to-fail/), [05](https://johnkaranja.com/guide/all-or-nothing/), [07](https://johnkaranja.com/guide/least-power/), [15](https://johnkaranja.com/guide/ship-safely/) of the [field guide](https://johnkaranja.com/guide/).
[For the Money (payments and ledgers) edition]
#### You get
- A payment-state map
- Findings you can trace, and the evidence that is missing
- A list of failure cases to test
- Fixes in order, each with a "done when" check
- A call to go through it, and one round of questions
Not included: financial audit, tax or accounting opinion, smart-contract audit, handling passwords or keys, moving funds or building the fixes.
Checked against rules [04](https://johnkaranja.com/guide/safe-to-repeat/), [06](https://johnkaranja.com/guide/money-in-whole-numbers/), [10](https://johnkaranja.com/guide/expect-failure/), [11](https://johnkaranja.com/guide/blockchain-final/), [12](https://johnkaranja.com/guide/one-writer/) of the [field guide](https://johnkaranja.com/guide/).
[For the AI at work edition]
#### You get
- A short report that keeps evidence apart from guesses
- A map of the workflow and who approves what
- A trial plan: what counts as success, and when to stop
- Next steps, in order
- A call to go through it, and one round of questions
Not included: training AI models, access to live systems, legal advice on data rights, or promises about accuracy or returns.
Checked against rules [13](https://johnkaranja.com/guide/ai-on-a-budget/), [03](https://johnkaranja.com/guide/choose-how-to-fail/), [09](https://johnkaranja.com/guide/layers-of-protection/), [14](https://johnkaranja.com/guide/tests-decide/) of the [field guide](https://johnkaranja.com/guide/).
[For the Technical lead edition]
#### You get
- A diagram of the system today, and a list of who has access
- Findings, riskiest first, with evidence and what is still unknown
- A plan for the first 30 days
- What a part-time technical lead would own, week by week
- A call to go through it, and one round of questions
Not included: code changes during the review, security certification, hiring or employment terms.
Checked against rules [01](https://johnkaranja.com/guide/one-source-of-truth/), [07](https://johnkaranja.com/guide/least-power/), [12](https://johnkaranja.com/guide/one-writer/), [15](https://johnkaranja.com/guide/ship-safely/), [16](https://johnkaranja.com/guide/fix-the-cause/) of the [field guide](https://johnkaranja.com/guide/).
[For the Investor (due diligence) edition]
#### You get
- A risk report, each point linked to its evidence
- Checked facts kept apart from seller claims and missing evidence
- Questions for the technical team
- Conditions to set before signing, and a handover outline
- A call to go through it, and one round of questions
Not included: valuation, investment advice, legal ownership opinion, financial audit, exhaustive code or security audit.
Checked against rules [07](https://johnkaranja.com/guide/least-power/), [01](https://johnkaranja.com/guide/one-source-of-truth/), [14](https://johnkaranja.com/guide/tests-decide/), [15](https://johnkaranja.com/guide/ship-safely/) of the [field guide](https://johnkaranja.com/guide/).
[For the Team training edition]
#### You get
- A short pre-call to choose the task and the codebase
- A full day, hands-on, on your own code
- A shared rule file and a review checklist
- A one-page plan for the next month
- One follow-up call two weeks later
Not included: building your product, tool licences, model training or certification.
Checked against rules [13](https://johnkaranja.com/guide/ai-on-a-budget/), [14](https://johnkaranja.com/guide/tests-decide/), [15](https://johnkaranja.com/guide/ship-safely/), [16](https://johnkaranja.com/guide/fix-the-cause/) of the [field guide](https://johnkaranja.com/guide/).
[Request this](https://johnkaranja.com/book/request/) [All offers on one page](https://johnkaranja.com/offers/)
Paid by USD invoice before the work starts, or through Upwork, which holds the payment until the work is done. Prices exclude any taxes that apply to you.

## Page: https://johnkaranja.com/book/request/
The last page · your request
### What is the next decision your system needs?
Five short answers. I reply within two working days, and nothing starts before we agree the scope in writing.
- You send the request below, or write in your own words.
- I reply with a short scope note and dates, or an honest "not a fit" and where I would look instead.
- We agree scope, materials and read-only access. Then the review is booked.
Please leave out passwords and production credentials. Nothing you type here is sent or stored by this page: it only opens your own email. [Privacy](https://johnkaranja.com/privacy/)
Or write to [info@johnkaranja.com](mailto:info@johnkaranja.com)
Prefer a platform? [Discuss your brief on Upwork](https://www.upwork.com/freelancers/~01cf385f9edbd7c565).

## Page: https://johnkaranja.com/book/colophon/
The end. Or the first page of yours.
An old soul who builds new things. When the wood is quiet, I make music.
Colophon
### How this book was made
Set in Fraunces and Lora, with original bee and honeycomb drawings. Written, designed and built by John, and served from his own server with no third-party trackers. The logo, qwainaina, reads “cue Wainaina”: my middle name written as a musical score, one bar for each letter.
Behind the book, my name runs along a stave of music, and a bee dances across it. Bees dance to show the hive where the honey is. This book does the same for your system.
[Read this book as a plain page] [All offers on one page](https://johnkaranja.com/offers/) [How my name became music](https://johnkaranja.com/score/) [The field guide](https://johnkaranja.com/guide/) [Privacy](https://johnkaranja.com/privacy/)
© 2026 John Wainaina Karanja · [X](https://x.com/qwainainaX) · [LinkedIn](https://www.linkedin.com/in/qwainaina) · [GitHub](https://github.com/qwainaina)
[Request a review](https://johnkaranja.com/book/request/)

# Sample report: payments and ledger check
Source: https://johnkaranja.com/samples/pay/

Illustrative sample · a fictional system, not a client's
## Payments and ledger integrity check: the rewards app
Prepared by John Karanja · fixed scope · Sample, November 2026
One payout flow in a rewards app that pays players small amounts of cryptocurrency for correct answers. It runs from the player's answer, through the score service and the reward claim, to the payout sender and the chain. Traced on a sample of records and logs with private details removed; no live transactions, logins or access to funds. This is not a financial audit, a smart-contract audit, or a tax or accounting opinion.
### Summary
When nothing goes wrong, the flow works. The sample holds 1,240 payout rows from 6 to 12 October. Every row marked sent has a matching transfer on the chain. The weak point is a chain that does not answer in time. The sender treats this timeout as a failure and sends again. Nothing in the records shows the request was already claimed. The sender log shows 37 timeouts that week. For 4 of them, the chain shows two transfers of the same amount to the same wallet. The balance a player sees is also kept in two places, and nobody compares them. The first fix is small and comes before anything else: claim each request before sending it.
- Sound: each confirmed payout matches one row in the payout table, and the scoring rules are well tested.
- Fragile: a timeout triggers an unchecked retry, which can pay the same request twice.
- Do first: a claim record with a unique request id, checked before every send.
### Scope and method
In scope: the payout flow from answer to chain, the payout table, the reward balance held by the score service, the sender's retry logic and the operations guide. Not in scope: smart contracts, who holds the wallet keys, in-app purchases, security testing, financial audit, tax and accounting.
Materials reviewed:
- Read-only access to the code of the score service and payout sender, as it was on 14 October.
- An export of the payout table for 6 to 12 October, with private details removed: 1,240 rows, 1,212 marked sent and 28 failed.
- The payout sender log for the same week.
- Public chain records for the app's sending wallet over the same week.
- The four-page operations guide and a short architecture note from the founding developer.
- Two calls with the founder and the developer.
Evidence has three labels. Observed: I saw it in the materials, and I name the source. Reported: the team told me, and I did not check it. Unknown: the evidence was not available. I never count an unknown as zero.
### The map
- Player answers The app records each answer and sends it to the score service with the player and question ids.
- Score service 3 It scores answers and keeps its own running reward balance for each player.
- Reward claim When a player taps claim, a row is written to the payout table with the amount and wallet address, marked pending.
- Payout sender 1 Every 15 seconds, a worker picks up pending rows. It sends the transfer without first recording that it has claimed the row.
- The chain 2 The sender waits 30 seconds for an answer, then treats silence as failure and resends without checking.
### Findings
#### 1. A payout can be sent twice
High
**Evidence:**
Observed. The sender retries on a timeout, and nothing records that a request was already claimed. A row stays pending until the chain confirms it. The sender log for 6 to 12 October shows 37 timeouts. For 4 of them, the chain records show two transfers of the same amount to the same wallet within two minutes, but only one row in the payout table.
**Impact:**
Each double send is money that leaves the wallet without showing in the records. It cannot be recovered without the player's help. Timeouts happen most at busy times (31 of the 37 fell between 19:00 and 22:00), so the risk grows with use.
**Unknown:**
Nothing important.
**Recommendation:**
Claim each request before sending. Write a claim record with a unique request id in the same database transaction that moves the row out of pending. A retry checks the claim first, and never decides to send on its own.
**Done when:**
In a test environment, force a timeout on the chain call 20 times. The chain shows exactly one transfer per request.
#### 2. A timed-out payout has no owner
High
**Evidence:**
Observed. Timeouts are only logged as warnings; no person reviews them. The payout table has three states: pending, sent and failed. There is no state for "we do not know". The guide says to "check the logs if a player complains" and names no person.
**Impact:**
A payout with an unknown result is either sent again without checking, as in finding 1, or forgotten. A player who was not paid has to notice and complain. A player paid twice is never found.
**Unknown:**
Nothing important.
**Recommendation:**
Add an "uncertain" state. Before any retry, check the row against the chain (reconcile it). Only a row confirmed absent from the chain may be sent again. Name one person who reviews any row left uncertain for more than an hour.
**Done when:**
Replay the 37 timeouts from 6 to 12 October through the reconciliation step. Each ends as sent or failed, with the chain record that decided it.
#### 3. Two records hold one balance
Medium
**Evidence:**
Observed. The score service and the payout table each keep a total. No job compares the two.
**Impact:**
When they differ, nobody can say which is right, and a player's complaint cannot be answered from the records.
**Unknown:**
How often they have differed. The export did not include the score service balances, so no comparison was possible.
**Recommendation:**
Pick the one record that counts; work out the other from it. Until then, compare them daily.
**Done when:**
For a sample of 200 players, the balance on screen equals the sum of their payout rows. The daily comparison shows no unexplained difference for seven days in a row.
#### 4. Wallet top-ups are not recorded
Medium
**Evidence:**
Observed. The guide says the founding developer tops up the sending wallet "when it runs low". The chain records show three top-ups in the week reviewed. None appears in the payout table or in any other record supplied.
**Impact:**
The wallet balance cannot be checked against the records. Money coming in is invisible, so a double send looks like ordinary spending.
**Unknown:**
Who else can top up or withdraw from the wallet. Who holds the keys was out of scope.
**Recommendation:**
Record every top-up with its chain reference. Reconcile daily: opening balance, plus top-ups, minus confirmed sends, equals the closing balance on the chain.
**Done when:**
For the week reviewed, the daily check matches the chain balance, or lists each difference with a reason.
#### 5. The failure cases have no tests
Medium
**Evidence:**
Observed. The test suite has 46 tests for the scoring rules and 3 for the payout sender, all on the success path. None covers a timeout, a duplicate claim, a rejected transfer or a restart in the middle of a send.
**Impact:**
The fixes for findings 1 and 2 cannot be shown to work, and a later change could undo them without anyone noticing.
**Unknown:**
Nothing important.
**Recommendation:**
Add tests for six failure cases: a timeout before the transfer goes out, a timeout after it, a double tap on claim, a restart between send and mark, a rejected transfer, and an empty wallet.
**Done when:**
All six tests run on every change. Putting the unchecked retry back makes at least one of them fail.
#### 6. A double tap can create two claims
Low
**Evidence:**
Observed. The claim step does not check for an existing pending claim. In the export, 9 players have two claim rows written within one second. In each case the second row failed at send, with "insufficient balance" read from the score service.
**Impact:**
Today the second claim fails only by luck. Fixing finding 3 would remove that protection.
**Unknown:**
Nothing important.
**Recommendation:**
The claim button sends a request id, and the claim step refuses a second pending claim for the same player.
**Done when:**
Two claims submitted within 100 milliseconds produce one row.
### What is sound
- Confirmed payouts match. All 1,212 rows marked sent have a chain transfer of the same amount to the same wallet.
- A row is marked sent only after the chain confirms it, not when the transfer is first sent.
- The scoring rules are well tested: 46 tests with clear names, all passing at the version reviewed.
- Wallet addresses are checked at claim time, and the export shows no transfer to a badly formed address.
### Action plan
#### First
- Add a claim record with a unique request id.
- The sender refuses any request without a claim.
- Done when: a forced timeout never causes a second send.
#### Next
- Add the uncertain state and the reconciliation step, and name the person who reviews uncertain rows.
- Run the six failure tests on every change.
- Record wallet top-ups and start the daily wallet reconciliation.
#### Later
- Make the payout table the one balance that counts; work out the screen figure from it.
- Refuse duplicate claims by request id.
- Review the reconciliation results once a month, and decide what to do about the 4 double sends already found.
### Open questions
- Can a transfer carry a unique reference on the chain in use? This decides whether reconciliation matches by request id or by wallet, amount and time.
- Who holds the sending wallet's keys, and who can move funds? Out of scope, but it matters to finding 4.
- Should the 4 double sends be recovered from players? That is a business decision, not a technical one.
### Next steps
I walk you through the findings on a call, then answer one round of written questions. If you hire me for the fixes within 60 days, this check's full fee comes off their price.
This is a sample: a fictional system, written like a real report. A real report follows the scope we agree in writing.
[Request a review](https://johnkaranja.com/book/request/?path=pay)
John Wainaina Karanja · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/)

# Sample report: AI readiness review
Source: https://johnkaranja.com/samples/ai/

Illustrative sample · a fictional system, not a client's
## AI readiness review: the invoice payment agent
Prepared by John Karanja · fixed scope · Sample, November 2026
One workflow: an agent (a program that takes actions) reads invoices sent to a shared inbox. It uses an AI model to pull out the details, and drafts a supplier payment for a person to approve. Is it ready for a small, limited trial (a pilot)? What needs evidence first? How do people stay in control when it fails? The agent drafts payments; it never releases them. Out of scope: model training, the choice of model, live-system access, legal opinions on data rights and any promise of accuracy.
### Summary
The agent is not ready for a pilot yet, but it is close. It reads invoices from regular suppliers well. In a one-time check of 120 October drafts, the amount matched the invoice in 117. The weak points are around the model, not in it. The agent drafts a payment for any sender. Nobody can say whether a change made it better or worse. The approver sees only the total. Each of these can be fixed in days. Fix the sender rule first, then build the test set, then run a four-week pilot with the stop rules below.
- Sound: it reads known suppliers' invoices well, and it cannot release a payment.
- Fragile: it acts on mail from anyone, and the approver cannot see what they are approving.
- Do first: approved suppliers only, with every invoice matched to a purchase order.
### Scope and method
In scope: the path from the shared inbox to the ledger, the agent's instructions and configuration, the approval screen and the people who use it. Not in scope: the bank's own systems, how the AI model works inside, model training, accounting rules, and legal questions about sending invoices to an AI model.
Materials reviewed:
- Read-only access to the agent's code, instructions and configuration, with their change history.
- The agent's run log for 1 to 31 October: 164 messages read and 151 drafts created.
- A copy of the October inbox and attachments, private details removed.
- Screenshots of the approval screen and the two-page approver guide.
- The supplier list from the ledger: 212 suppliers, 58 of them paid in the last 90 days.
- Two calls, one with the finance lead and one with the developer who built the agent.
Evidence has three labels. Observed: I saw it in the materials, and I name the source. Reported: the team told me, and I did not check it. Unknown: the evidence was not available. I never count an unknown as zero.
### The map
- Shared inbox 1 Every 10 minutes, the agent collects all mail sent to the accounts address, from any sender.
- Invoice reader An AI model pulls the supplier name, bank details, amount, due date and invoice number from the attachment.
- Draft payment 2 The agent matches the supplier name to the ledger and creates a draft. No tests check changes to how it does this.
- Approval 3 One of two finance staff approves or rejects each draft. They see only the total, the supplier name and the due date.
- Ledger Approved drafts are posted to the ledger, and a person releases the payment in the bank's system.
### Findings
#### 1. The agent acts on mail it should not trust
High
**Evidence:**
Observed. Invoices from any sender are read and drafted, including first-time senders. Of the 164 messages in October, 13 came from addresses not seen before, and the agent drafted payments for 9 of them. Two of those 9 carried bank details different from the ledger's for a supplier of the same name. Both were rejected, by an approver who recognised the change.
**Impact:**
A changed bank account on a convincing invoice is a known way to pay the wrong party. Today the only protection is one person's memory.
**Unknown:**
Nothing important.
**Recommendation:**
Act only on approved suppliers, and match every invoice to a purchase order. Mail from an unknown sender goes to a review queue, never to a draft. A change of bank details is confirmed by a person, outside email.
**Done when:**
Replay the 13 unknown-sender messages from October. None produces a draft, and all 13 appear in the review queue.
#### 2. Nobody can say whether a change helped
High
**Evidence:**
Observed. There is no set of past invoices with known correct drafts. The agent's instructions changed four times in October, according to the change history. Reported: after each change the developer checks "a few recent invoices" by eye. In my one-time check, the three wrong amounts were all on multi-page invoices, where the agent took the subtotal before tax.
**Impact:**
Every change is a guess. If a change broke multi-page invoices, nobody would know until someone was paid the wrong amount.
**Unknown:**
Nothing important.
**Recommendation:**
Keep 30 past invoices as a test set and run it before each change. The finance lead writes down the correct draft for each. Include the three multi-page cases, five unknown senders and the two changed bank details.
**Done when:**
The set exists, today's score is recorded, and no change is accepted that scores lower.
#### 3. Approval is only a formality
Medium
**Evidence:**
Observed. The approver sees the amount, not the source invoice or what the agent changed. The screen shows the supplier name, total and due date, and nothing else. The run log shows a median of 9 seconds between opening a draft and approving it.
**Impact:**
An approver cannot catch what they cannot see. The two rejections in finding 1 relied on memory, not on the screen.
**Unknown:**
How many drafts were approved unread. A short approval time is not proof either way.
**Recommendation:**
Show the source document and the agent's reasoning beside every approval: the invoice image, the extracted fields, the bank details compared with the ledger, and any field the agent was unsure of.
**Done when:**
In a test with 10 drafts, 2 with changed bank details, the approver sees both changes flagged without opening another system.
#### 4. Unsure results look the same as sure ones
Medium
**Evidence:**
Observed. The model returns a note on each field it was unsure of, and the agent throws it away. The run log shows 6 drafts with no due date on the invoice. For each, the agent filled in that day's date.
**Impact:**
On the approval screen, a guess looks the same as a fact.
**Unknown:**
Nothing important.
**Recommendation:**
When a field is empty or marked unsure, the draft is marked "needs a person" and names the field. The agent never fills a default.
**Done when:**
Replayed, the 6 October cases are all marked "needs a person".
#### 5. There is no written list of what it must never do
Low
**Evidence:**
Observed. No document states the agent's limits. Its instructions tell it to "complete the payment details where possible". It can read the whole supplier list, including bank details, though it only needs names and purchase orders.
**Impact:**
With no written limits, its users will be the first to test them.
**Unknown:**
Nothing important.
**Recommendation:**
Write a one-page list: never release a payment, never change a supplier record, never act on an unapproved sender, never fill a missing field, never draft above a limit set by finance. Enforce each item in code, not only in the instructions.
**Done when:**
Each item has a check in code and a case in the 30-invoice test set.
#### 6. A draft cannot be traced to the version that made it
Low
**Evidence:**
Observed. The run log records the message and the draft, but not the model's raw output or which version of the instructions was in use. For 3 October drafts I could not tell which version produced them.
**Impact:**
A mistake cannot be explained, so its cause cannot be fixed.
**Unknown:**
Nothing important.
**Recommendation:**
With each draft, store the message, the attachment, the instructions version and the model's raw output.
**Done when:**
For any draft, one query returns its source email, instructions version and raw output.
### What is sound
- It reads regular suppliers' invoices well: 117 of 120 amounts matched in the one-time check.
- The agent cannot release money. It can only write drafts, and a person releases payments in the bank's system.
- The approvers do reject. Both changed bank details in October were caught, even without help from the screen.
- The code is small and readable. The developer explained every step of it in one call.
### Action plan
#### First
- Add an approved-supplier list and purchase-order matching.
- Build the 30-invoice test set and record today's results.
- Done when: an invoice from an unknown sender is never drafted.
#### Next
- Rebuild the approval screen to show the source invoice, the bank-detail comparison and unsure fields.
- Mark unsure or empty fields as "needs a person".
- Run a four-week pilot on approved suppliers only, with a per-draft limit set by finance.
- Pilot success: at least 28 of 30 on the test set, every draft traceable, no draft from an unknown sender.
- Pilot stop: any draft from an unknown sender, any unflagged change of bank details, or a test score below 27 of 30.
#### Later
- Enforce the never-do list in code, with a test for each item.
- Store the full trace for every draft.
- Review the pilot results with finance before adding more suppliers.
### Open questions
- Who owns the approved-supplier list, and how is a new supplier added?
- What share of invoices arrive with a purchase order? If many do not, matching needs another rule.
- Has any approved draft been paid to the wrong party since launch? Bank records were not supplied.
- Are there data rights questions about sending invoices to an AI model? That needs your legal adviser.
### Next steps
I walk you through the findings and the pilot plan on a call, then answer one round of written questions. If you hire me to build the pilot within 60 days, this review's full fee comes off its price.
This is a sample: a fictional system, written like a real report. A real report follows the scope we agree in writing.
[Request a review](https://johnkaranja.com/book/request/?path=ai)
John Wainaina Karanja · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/)

# Sample report: architecture review or handover check
Source: https://johnkaranja.com/samples/lead/

Illustrative sample · a fictional system, not a client's
## Architecture review and handover check: the marketplace
Prepared by John Karanja · fixed scope · Sample, November 2026
One product: a marketplace where buyers book and pay for services from independent providers. One developer built it in about five months, working with AI coding agents. Paying customers use it now. The review covers how it is built, who holds what, what breaks first, and a plan for the first 30 days. No code was changed during the review. Out of scope: security certification, penetration and load testing, and hiring or employment terms.
### Summary
The marketplace works. Its code is tidier than such a fast build would suggest. The main booking journey is tested, and the API follows one pattern throughout. The risk is not in the code but around it. One developer holds every key. Releases are copied to the server by hand, with no way back. The nightly backups have never been restored. None of this needs a rewrite. In the first 30 days: share ownership, add a release pipeline and prove that a restore works.
- Sound: a tested booking journey, payment confirmed by the provider, and a consistent API.
- Fragile: one person and one laptop hold every account, and no release can be undone.
- Do first: an access register and a second owner on every account.
### Scope and method
In scope: the web app, the API, the database, the link to the payments provider, the release process and every account the product depends on. Not in scope: code changes, the payments provider's own systems, security certification, penetration and load testing, and legal questions about who owns the code.
Materials reviewed:
- Read-only access to the code repository, as it was on 20 October.
- The release notes the developer posts in the team chat for the last 90 days.
- A list of accounts made with the developer on the first call. It became the access register.
- The backup settings and a listing of stored backups.
- An export of 2,310 bookings from the last 90 days, private details removed, and the API logs for 20 to 26 October.
- Two calls, one with the founder and one with the developer.
Evidence has three labels. Observed: I saw it in the materials, and I name the source. Reported: the team told me, and I did not check it. Unknown: the evidence was not available. I never count an unknown as zero.
### The map
- Web app A single-page app where buyers search, book and pay. It runs on the same server as the API.
- API 2 One service handles search, bookings, provider payouts and the admin pages. It is deployed by hand.
- Database 3 One managed database, with a nightly backup kept for seven days. The restore has never been tested.
- Payments provider It takes card payments and tells the API. The API confirms a booking only when that notice arrives.
- One laptop 1 The developer's laptop holds every key: the server key, the cloud and domain accounts, and the settings file with every password.
### Findings
#### 1. One person holds every key
High
**Evidence:**
Observed. Live-system access, release rights and the domain account sit with one developer. The access register lists 14 accounts; 12 are registered to the developer's personal email, and the founder is an administrator on only 2. The server accepts a key held only on the developer's laptop. The domain renews in seven weeks on the developer's personal card.
**Impact:**
If the developer is ill, leaves or loses the laptop, nobody can ship a fix, renew the domain or change a password. The product depends on one person's health and goodwill.
**Unknown:**
Nothing important.
**Recommendation:**
An access register, shared ownership of every account, and releases from a pipeline. Every account moves into the company's name, with at least two administrators.
**Done when:**
The founder signs in as an administrator on all 14 accounts, and a second person ships a change without the developer's laptop.
#### 2. No way back from a bad release
High
**Evidence:**
Observed. Changes are copied to the server by hand; there is no previous version to return to. The release notes show 41 releases in 90 days. Three of them were followed within an hour by a second release labelled "hotfix".
**Impact:**
A bad release can only be fixed by writing another one under pressure, while customers wait.
**Unknown:**
Nothing important.
**Recommendation:**
Add a release pipeline that can roll back in one step. It runs the tests, builds once, keeps the last five versions, and returns to any of them with one command.
**Done when:**
A broken build, released to a test server on purpose, is rolled back in under five minutes, timed.
#### 3. The backups have never been restored
Medium
**Evidence:**
Observed. Nightly backups exist. Seven are kept, and the latest is 2.1 GB. No restore is recorded anywhere, and the developer could not remember one.
**Impact:**
A backup that has never been restored is a hope, not a recovery plan.
**Unknown:**
Whether one has ever been restored, and how long it takes.
**Recommendation:**
Restore into a separate database once a month, and time it.
**Done when:**
Last night's backup is restored, the booking count matches the live database, and the time taken is written down.
#### 4. Passwords were once saved in the code
High
**Evidence:**
Observed. The settings file holds the database password and the payments provider and email keys. The repository history shows the file was added in the first month and deleted later, so the values are still in the history. I did not open or copy them.
**Impact:**
Anyone with access to the repository, now or in the past, can read those keys.
**Unknown:**
Whether the keys have changed since. Reported: they have not.
**Recommendation:**
Change every key that was in the history, remove the file from the history, and keep secrets in a store the company controls.
**Done when:**
The old keys are refused, and a scan of the full history finds no secret.
#### 5. Payments without a booking go unnoticed
Medium
**Evidence:**
Observed. The API log shows 6 payment notices refused with errors during a release on 22 October. The provider sends notices again, but nothing compares payments taken with bookings confirmed. The export shows 2 bookings that were paid but still say "awaiting payment".
**Impact:**
A customer can be charged with no booking to show for it, and the business finds out from the complaint.
**Unknown:**
Nothing important.
**Recommendation:**
A daily job that compares the provider's payment report with confirmed bookings, and refuses a second notice for the same payment.
**Done when:**
The first run lists the 2 known cases, and the job runs for seven days with every mismatch explained.
#### 6. Search will slow down first as use grows
Low
**Evidence:**
Observed. The main search filters on two columns with no index. The busiest hour in the logs was a Saturday morning with 61 bookings. Its slowest search took 2.4 seconds; the median was 180 milliseconds.
**Impact:**
Search is the first part likely to fail under more use.
**Unknown:**
How it behaves with more traffic. Load testing was out of scope.
**Recommendation:**
Add the index, then measure the slowest search each week.
**Done when:**
At the next Saturday peak, the slowest search takes under one second.
### What is sound
- The booking journey is tested: 38 tests cover search, booking and cancellation, and all pass at the version reviewed.
- A booking is confirmed only when the payments provider says so, never on the browser's word.
- Every API endpoint follows the same pattern, so a newcomer can read the code easily.
- The database is managed, and its nightly backups run without anyone touching them.
### Action plan
#### First
- Week one: an access register and a second owner on every account.
- Weeks two and three: a release pipeline with one-step rollback.
- Done when: last night's backup is restored, timed and written down.
#### Next
- Change the keys that were in the history and move secrets to a company-held store.
- Start the daily comparison of payments and bookings.
- Add the search index and the monthly restore test.
#### Later
- A two-page architecture note and a release checklist, so a second developer can start in a week.
- If hired, a part-time technical lead would own the access register, release checklist and monthly restore, and review every release in the first month.
### Open questions
- Is the developer staying, and for how long? The answer sets the pace of the handover.
- Who owns the code the developer wrote? That is a question for your legal adviser, not this review.
- How long could the business accept the site being down? That sets the target for the restore test.
### Next steps
I walk you through the findings and the 30-day plan on a call, then answer one round of written questions. If you hire me as your part-time technical lead within 60 days, this review's full fee comes off that price.
This is a sample: a fictional system, written like a real report. A real report follows the scope we agree in writing.
[Request a review](https://johnkaranja.com/book/request/?path=lead)
John Wainaina Karanja · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/)

# Sample report: technical due diligence
Source: https://johnkaranja.com/samples/invest/

Illustrative sample · a fictional system, not a client's
## Technical due diligence: the stock-tracking software
Prepared by John Karanja · fixed scope · Sample, November 2026
Technical due diligence for a buyer of a small software business. It sells stock-tracking software by subscription to independent shops with more than one branch. Two developers maintain it: the founder and a part-time developer. The review checks the seller's technical claims against the system. It sets out the risks, open questions and handover problems before signing. Out of scope: valuation, investment advice, legal ownership opinions, financial audit and a complete code or security audit.
### Summary
The product works. The database holds 84 subscriber accounts marked active, which matches the seller's figure. Two things do not match the deck. The code repository and the cloud account are registered to a former contractor, not the business. And the "real-time" stock sync runs only once a night. Customer data is backed up every night but has never been restored. On technical grounds, none of these needs to stop the deal. But each should be settled before signing. The decision to buy, and the price, stay with the buyer and their advisers.
- Sound: a working product with tested stock and billing logic, and a clear data model.
- Fragile: the business does not control its own code, and only the founder can release updates.
- Do first: make the transfer of the repository and the cloud account a condition of signing.
### Scope and method
In scope: the code, the hosting and domain accounts, the customer database, backups, the release process and the technical claims in the seller's deck and sale documents. Not in scope: valuation, revenue or customer contracts, legal ownership of the code, financial audit, penetration testing and a line-by-line code audit.
Materials reviewed:
- The seller's 18-slide deck and the technical section of the sale documents.
- Read-only access to the code repository, granted for the review.
- A read-only view of the cloud account's resources and six months of hosting invoices.
- The database structure and row counts, with no customer records.
- The sync job's settings and its log for 1 to 30 September.
- Two calls with the founder and the part-time developer, and written answers to 22 questions.
Evidence has three labels. Observed: I saw it in the materials, and I name the source. Reported: the seller told me, and I did not check it. Unknown: the evidence was not available. I never count an unknown as zero.
### The map
- Seller's deck 2 The deck and sale documents describe the product. They claim "real-time" stock sync across branches.
- Code repository 1 One repository with four years of history and 2,900 changes, owned by a former contractor.
- Hosting accounts The cloud account runs two servers and the managed database. The domain is held separately, in the business's name.
- Customer data 3 One database holds stock records for every subscriber. It is backed up nightly, but the restore has never been tested.
- Handover What would move to the buyer at signing: code, accounts, domain and knowledge, today written down in one three-page note.
### Findings
#### 1. The code belongs to someone else
High
**Evidence:**
Observed. The repository and the cloud account are registered to a former contractor, who made 1,770 of the 2,900 changes in the first three years. The cloud bill goes on the contractor's card, then is charged to the business monthly. Reported: the contractor "has agreed to transfer". No written agreement is in the data room.
**Impact:**
Without the transfer, the buyer may be buying a licence, not a product. The contractor could remove access at any time. Legal ownership is for the buyer's lawyers. This finding is about who controls the systems.
**Unknown:**
Nothing important.
**Recommendation:**
Make the transfer of both a condition of signing.
**Done when:**
At signing, the buyer's own administrator holds owner rights on the repository and the cloud account. The contractor's access is removed.
#### 2. "Real-time" runs once a night
High
**Evidence:**
Observed. The sync job runs once a day; the deck says real-time. It starts at 02:00. Its log shows 30 runs in September, taking 47 minutes on average. Slide 7 and section 3 of the sale documents both say "real-time stock sync across branches".
**Impact:**
Customers see yesterday's stock in other branches. Any plan that relies on real-time sync, such as selling to larger chains, rests on a feature that does not exist.
**Unknown:**
Nothing important.
**Recommendation:**
Correct this assumption in the valuation, or require the fix before closing. The team should estimate the work. My rough view: weeks, not days.
**Done when:**
Either the sale documents are corrected in writing, or a stock change in one branch appears in another within 60 seconds, shown on live data.
#### 3. Customer data has never been restored
Medium
**Evidence:**
Observed. Backups run nightly, and 14 are kept. No restore is recorded, and neither developer could remember one.
**Impact:**
If a restore fails after the deal, the buyer carries the loss of every subscriber's records.
**Unknown:**
Whether a restore works, and how long it takes.
**Recommendation:**
A witnessed restore test before signing.
**Done when:**
The latest backup is restored to a separate database in front of the buyer's representative. The row counts of the five main tables match the live database. The time is recorded.
#### 4. Only the founder can release
Medium
**Evidence:**
Observed. The release log shows 112 releases in 12 months, all by the founder, from the founder's own computer. There is no written release procedure.
**Impact:**
If the founder left after the deal, all change to the product would stop.
**Unknown:**
How long the founder will stay after the deal.
**Recommendation:**
A written release procedure, and a handover period for the founder, agreed in the deal.
**Done when:**
The part-time developer makes one release from the written procedure, without the founder's help.
#### 5. The running cost is higher than stated
Medium
**Evidence:**
Observed. The deck says hosting costs about USD 900 a month. The invoices show USD 1,140 to 1,260 over the last six months. One of the two servers has run below 2 per cent of its capacity for 30 days.
**Impact:**
A running cost nobody can explain usually grows after the deal, not before.
**Unknown:**
What the idle server is for. The founder was not sure.
**Recommendation:**
An itemised bill from the cloud account, and a decision on the idle server, after the transfer.
**Done when:**
One month's bill names every resource and what it is for.
#### 6. The main framework no longer gets security fixes
Low
**Evidence:**
Observed. The web framework is three major versions behind, and the version in use no longer receives security fixes from its maintainers.
**Impact:**
An upgrade is a cost the buyer inherits.
**Unknown:**
The size of the upgrade. The sync job has no tests, which makes it harder to estimate.
**Recommendation:**
An upgrade plan within the first 90 days, budgeted before signing.
**Done when:**
A written estimate from the team, agreed by the buyer before signing.
### Seller claims checked
ClaimEvidence foundStatus
Real-time stock sync across branchesRuns once a night at 02:00; 30 runs in the September logContradicted
The business owns all its codeRepository and cloud account registered to a former contractor; no transfer agreementNot verified
84 active customers84 accounts marked active in the database; payments not checkedPartly verified
Daily backups of all customer dataNightly backups, 14 kept; never restoredPartly verified
Hosting about USD 900 a monthInvoices of USD 1,140 to 1,260 a monthContradicted
Two developers can maintain the productBoth write code; only the founder has releasedPartly verified
Core features fully tested210 tests; stock and billing covered, sync job notPartly verified
Customer records stored in one databaseSchema and row counts show one databaseVerified
### What is sound
- The stock and billing logic is tested: 210 tests, all passing at the version reviewed.
- The data model is clear. Each branch, product and stock movement has its own table, and the schema matches the architecture note.
- The domain is registered to the business, and renews automatically.
- The founder's written answers were complete and matched what the system showed, apart from the points above.
### Conditions before signing, and the handover plan
#### First
- Ownership of code, accounts and domains transferred at signing.
- A witnessed restore of customer data.
- The real-time claim corrected in the sale documents.
#### Next
- At signing: a written release procedure, and one release made from it by the part-time developer.
- A handover period for the founder, agreed in the deal, with a weekly handover session.
- All passwords and keys changed once the contractor's access is removed.
#### Later
- First 90 days: an itemised bill, a decision on the idle server, and a framework upgrade plan.
- Tests for the sync job, then a decision on whether to build real-time sync.
### Open questions
- Does the contractor's agreement give ownership of the code to the business? That is for the buyer's lawyers.
- Do any customer contracts promise real-time sync?
- Has there been any security incident or data loss in four years? The seller says no; there is no record either way.
- Will the part-time developer stay after the deal?
### Next steps
I walk you through the findings on a call, then answer one round of written questions. If you hire me for the first-90-days technical plan within 60 days, this review's full fee comes off its price.
This is a sample: a fictional system, written like a real report. A real report follows the scope we agree in writing.
[Request a review](https://johnkaranja.com/book/request/?path=invest)
John Wainaina Karanja · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/)

# Sample workshop pack
Source: https://johnkaranja.com/samples/team/

Illustrative sample · a fictional system, not a client's
## Workshop pack: AI coding agents in a five-person team
Prepared by John Karanja · fixed scope · Sample, November 2026
A one-day, hands-on workshop for a five-person team. The team maintains a web application and has started using AI coding agents without agreed rules. The team builds one agent workflow from start to finish on its own code, and writes its own rules and review gate. This pack holds everything used on the day. Not included: building your product, tool licences, model training or certification.
### What you leave with
- A shared rule file for your agents. Written together on the day, for your own repository: what agents may change, what they must ask about, and what they must never touch.
- One working workflow. The team builds it from start to finish on a real task, as a pattern to copy for the next one.
- A review gate. Agent-written changes pass the same checks as human ones: a pull-request checklist for agent work, fitted to the checks your pipeline already runs.
### Agenda
#### Morning: how agents fail, and one workflow built together
- 09:00 to 09:30. Introductions, the chosen task, and what "done" means for it.
- 09:30 to 10:30. How agents fail: changes nobody asked for, confident wrong answers, tests edited to pass, and work that cannot be traced.
- 10:45 to 12:30. Build one workflow together, hands-on, on the chosen task.
#### Afternoon: rules and review gates on your own codebase
- 13:30 to 14:30. Write the rule file for your repository.
- 14:30 to 15:30. Build the review gate, and run it on the morning's change.
- 15:45 to 16:30. A second, smaller task, run by a different pair using the rules and the gate.
- 16:30 to 17:00. The one-page plan for the next month: who does what.
### Before the day: planning-call questions
A 30-minute call, about a week before, to choose the task and the codebase.
- Which repository will we work in, and can everyone run it locally on the day?
- Which AI coding agents does the team use now, and who uses them most?
- What is one real task, about half a day's work for one person, that is ready to start?
- What checks does your pipeline run on every change: tests, formatting, type checks, anything else?
- Which parts of the code does nobody want an agent to touch, and why?
- Has an agent-written change ever caused a problem? What happened?
- Who reviews changes today, and how long does a review usually wait?
### Rule file template
One file at the root of the repository, read by every agent and every person. Keep it short enough to read in two minutes. The team fills in the brackets on the day.
#### Agents may change
- Code inside the folders named for the task: [folders].
- Tests for the code they change, adding cases but never removing one.
- Documentation that describes the code they changed.
#### Agents must ask before
- Adding, removing or upgrading a dependency.
- Changing a database schema or a migration.
- Changing a public interface that other code or other teams rely on.
- Touching more than [number] files in one change.
#### Agents must never touch
- Secrets, keys, settings files with passwords, or anything in [secrets folder].
- Release, deployment or pipeline settings.
- Payment, authentication or permission code: [folders].
- An existing test, just to make it pass.
#### How agents work here
- One task per change, described in one sentence at the top.
- Run all the tests before proposing a change, and say which ones ran.
- When unsure, stop and ask. A question is better than a guess.
### Review checklist for agent-written changes
The same checks as a human change, plus six questions the reviewer answers before approving.
- Does the change do only what the task asked? Any file outside the task's folders needs a reason.
- Do all pipeline checks pass, and were no tests removed, skipped or weakened?
- Is every new dependency approved, as the rule file requires?
- Could the reviewer explain each changed line to a colleague without the agent's help?
- Is anything in the "never touch" list changed? If so, the change is refused.
- Is the change small enough to undo on its own?
### The hands-on exercise
The team works in pairs on the task chosen on the planning call. One person directs the agent. The other notes every point where the agent needed steering or correcting.
- Before the agent sees the task, write it as one sentence and three "done when" checks.
- Give the agent the task and the draft rules. Ask it for a plan first, and review the plan before any code is written.
- Let it work in small steps. After each step, run the tests and read the change.
- When it goes wrong, note what happened and which rule would have prevented it.
- Run the finished change through the review checklist, as a second pair would.
- Done when all three checks pass and the reviewer approves without the agent's help.
The notes from step 4 become new lines in the rule file in the afternoon.
### Next-month plan template
One page, written in the last half hour, and reviewed on the follow-up call.
- Owner of the rule file: [name]. Reviews proposed changes to it each week.
- Owner of the review gate: [name]. Turns manual checklist items into pipeline checks.
- Next three tasks for agents: [task], [task], [task], each with its "done when" checks.
- How we share lessons: [where and when], for example ten minutes at the weekly meeting.
- What we will measure: [for example, changes refused at review, and why].
- What we stop doing: [one habit the day showed to be risky].
### After the day
Two weeks later, one follow-up call reviews the plan, the rule file and anything the gate caught. If you hire me for team coaching within 60 days, the workshop's full fee comes off its price.
This is a sample: a fictional system, written like a real report. A real report follows the scope we agree in writing.
[Request a workshop](https://johnkaranja.com/book/request/?path=team)
John Wainaina Karanja · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/)

# The field guide: 16 rules for systems people trust
Source: https://johnkaranja.com/guide/

The field guide · free to read
## 16 rules for systems people trust
These are the rules I use to build software that handles money, data and AI. Each one takes about two minutes to read, in plain English, and ends with three questions to ask your own team.
By John Wainaina Karanja, product and systems lead since 2007. If a few answers come back "no" or "not sure", that is where a review starts.
- [01 Keep each fact in one placeDecide where each important fact lives, and let everything else read it from there.](https://johnkaranja.com/guide/one-source-of-truth/)
- [02 Check everything that comes inTreat anything from outside as possibly wrong, and check it the moment it arrives.](https://johnkaranja.com/guide/check-what-comes-in/)
- [03 Decide what happens when things breakWhen part of a system fails, choose whether it stops or carries on, by asking what a wrong answer would cost.](https://johnkaranja.com/guide/choose-how-to-fail/)
- [04 Make actions safe to repeatConnections drop and people press twice. An action that runs twice should have the same effect as running once.](https://johnkaranja.com/guide/safe-to-repeat/)
- [05 All or nothing: no half-done changesA change should happen completely or not at all, never halfway.](https://johnkaranja.com/guide/all-or-nothing/)
- [06 Store money in whole numbers, and make the books balanceNever store money in a way that rounds. Use whole cents, and write down the rule that must always hold.](https://johnkaranja.com/guide/money-in-whole-numbers/)
- [07 Give each part only the power it needsKeep keys out of the code, and design so that one broken part cannot do much damage.](https://johnkaranja.com/guide/least-power/)
- [08 Prove who is askingEvery request should prove who sent it, and that it was not changed or sent again.](https://johnkaranja.com/guide/prove-who-is-asking/)
- [09 Several simple guards beat one clever wallNo single check is perfect, so stack simple, separate guards. When one misses, the next one catches it.](https://johnkaranja.com/guide/layers-of-protection/)
- [10 Expect other services to failRetry what is safe, pause what keeps failing, keep a second source, and never blindly resend money.](https://johnkaranja.com/guide/expect-failure/)
- [11 On a blockchain, wait until it is finalThe newest blocks can be replaced. Wait for confirmations, count each transaction once, and refuse old requests.](https://johnkaranja.com/guide/blockchain-final/)
- [12 Let only one worker move the moneyWhen several copies of a program run at once, decide which jobs may run in one place only.](https://johnkaranja.com/guide/one-writer/)
- [13 Keep AI on a budget and on the factsTreat AI like any paid service that is sometimes wrong: cap the cost, give it checked facts, check its answers, and keep a person in charge.](https://johnkaranja.com/guide/ai-on-a-budget/)
- [14 Let tests decide when work is doneAgree what "correct" means as tests before you build, and for money, test the rule itself.](https://johnkaranja.com/guide/tests-decide/)
- [15 Ship only what was checked, and watch it runRelease exactly what was reviewed, check it after every release, keep a way back, and hear about problems before your users do.](https://johnkaranja.com/guide/ship-safely/)
- [16 Fix the cause, not just the symptomEvery system has bad days. What counts is a calm account of what happened, and a rule that stops it happening again.](https://johnkaranja.com/guide/fix-the-cause/)
### What to do next
Answer five questions about your own system and see which rule to look at first. Or ask the assistant about any rule.
[Check your system in one minute](https://johnkaranja.com/book/questions/) [Ask a question](https://johnkaranja.com/book/?ask=1) [Request a review](https://johnkaranja.com/book/request/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 01: Keep each fact in one place
Source: https://johnkaranja.com/guide/one-source-of-truth/

The field guide · rule 01 of 16
## Keep each fact in one place
Decide where each important fact lives, and let everything else read it from there.
### What it means
Before building anything, decide what the system stores, who owns each fact, and where the one true copy lives. If the same fact is kept in two places, sooner or later the two copies disagree, and nobody knows which one is right.
### What goes wrong without it
A customer's balance shows one figure in the app and another in the payout table. Support cannot answer, and the books cannot be trusted.
### How I build it
From systems I build and run.
- The spending limit in my AI agent system reads the same usage record that the meter writes, so there is no second spending figure to drift.
- The Space.ke assistant takes its facts from the same data the site's pages use, so the chat cannot contradict the pages.
- Prices in my chain-intelligence service live in one table the admin can edit, with safe defaults in the code if that row is missing.
### Ask your team
- For each important fact, can you name the one record that counts?
- If two records disagree, does anything warn you?
- Could a new developer find where a price or a balance is stored within an hour?
A "no" or "not sure" is worth a closer look.
### How a review checks this
Every review starts with a map of where each important fact lives, and marks any fact kept in two places.
[Request a review](https://johnkaranja.com/book/request/?path=any) [The offer: Architecture review](https://johnkaranja.com/book/offer/) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=any)
### Related rules
- [Rule 06: Store money in whole numbers, and make the books balance](https://johnkaranja.com/guide/money-in-whole-numbers/)
- [Rule 12: Let only one worker move the money](https://johnkaranja.com/guide/one-writer/)
[NextCheck everything that comes in](https://johnkaranja.com/guide/check-what-comes-in/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 02: Check everything that comes in
Source: https://johnkaranja.com/guide/check-what-comes-in/

The field guide · rule 02 of 16
## Check everything that comes in
Treat anything from outside as possibly wrong, and check it the moment it arrives.
### What it means
Anything that comes from outside the system might be wrong, or even hostile: what a user types, what a browser sends, what another service returns, even a settings file. Check it at the door. If the settings are wrong, the system should refuse to start, rather than fail halfway through a customer's request.
### What goes wrong without it
A payout address with one wrong character sends money to the wrong place, and there is no way to get it back.
### How I build it
From systems I build and run.
- My chain-intelligence service checks every setting when it starts. A bad setting stops it from starting at all.
- A contact form I built checks the email format and length, and removes hidden line breaks that could be used to send spam through it.
- My mining apps check wallet addresses with their built-in check digits, so a typo cannot send coins to the wrong place.
### Ask your team
- Do you check what users and other services send before you use it?
- Does the system refuse to start with bad settings?
- Is every amount and address checked before money moves?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review lists every place where outside data enters, and checks what happens when that data is wrong.
[Request a review](https://johnkaranja.com/book/request/?path=any) [The offer: Architecture review](https://johnkaranja.com/book/offer/) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=any)
### Related rules
- [Rule 09: Several simple guards beat one clever wall](https://johnkaranja.com/guide/layers-of-protection/)
- [Rule 08: Prove who is asking](https://johnkaranja.com/guide/prove-who-is-asking/)
[PreviousKeep each fact in one place](https://johnkaranja.com/guide/one-source-of-truth/) [NextDecide what happens when things break](https://johnkaranja.com/guide/choose-how-to-fail/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 03: Decide what happens when things break
Source: https://johnkaranja.com/guide/choose-how-to-fail/

The field guide · rule 03 of 16
## Decide what happens when things break
When part of a system fails, choose whether it stops or carries on, by asking what a wrong answer would cost.
### What it means
When something goes wrong, a system can stop, or it can carry on doing less. Choose by asking what it costs to be wrong. If the risk is losing money or leaking data, stop. If the risk is a report with one figure missing, carry on and say so.
### What goes wrong without it
A payment check times out and is treated as "paid", so someone gets access they never paid for.
### How I build it
From systems I build and run.
- In my AI agent system, if the spending meter cannot be read, every AI call is refused. If an AI answer cannot be read, the job carries on with an empty result.
- In my chain-intelligence service, if the database cannot confirm that a payment has not been used before, access is refused rather than risk giving it twice.
- My mining apps install nothing if a download's fingerprint is missing.
### Ask your team
- For each important step, do you know whether it stops or carries on when something fails?
- Does anything that touches money stop when it is unsure?
- Do people see a clear message when a part is unavailable?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review walks through what each important step does when the step before it fails, starting with the steps that touch money.
[Request a review](https://johnkaranja.com/book/request/?path=any) [The offer: Architecture review](https://johnkaranja.com/book/offer/) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=any)
### Related rules
- [Rule 10: Expect other services to fail](https://johnkaranja.com/guide/expect-failure/)
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
[PreviousCheck everything that comes in](https://johnkaranja.com/guide/check-what-comes-in/) [NextMake actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 04: Make actions safe to repeat
Source: https://johnkaranja.com/guide/safe-to-repeat/

The field guide · rule 04 of 16
## Make actions safe to repeat
Connections drop and people press twice. An action that runs twice should have the same effect as running once.
### What it means
Connections drop, servers restart and people press the button twice. A well-built action can run twice and still have the effect of running once. The safe way is a unique number for each request, which the database refuses to accept twice, rather than hoping everyone is careful. Engineers call this idempotency.
### What goes wrong without it
A payout times out, the system tries again, and the customer is paid twice.
### How I build it
From systems I build and run.
- My chain-intelligence service saves each transaction under its unique ID and skips it if it is already there, so reading again after a crash never makes duplicates.
- My finance back-office gives each statement import a unique key for each company and file. Running it again says "already imported" instead of counting it twice.
- In my reward systems, a withdrawal request carries its own unique key and is created in one locked step, so one click is one request, even if it is retried.
### Ask your team
- If the same request arrives twice, is the second one refused?
- Does a retry first check whether the first attempt already worked?
- Is the duplicate check in the database, not only in the code?
A "no" or "not sure" is worth a closer look.
### How a review checks this
The payments check forces timeouts and repeats on purpose, and shows whether anything is ever sent twice.
[Request a review](https://johnkaranja.com/book/request/?path=pay) [The offer: Payments and ledger integrity check](https://johnkaranja.com/book/offer/?path=pay) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=pay)
### Related rules
- [Rule 10: Expect other services to fail](https://johnkaranja.com/guide/expect-failure/)
- [Rule 05: All or nothing: no half-done changes](https://johnkaranja.com/guide/all-or-nothing/)
- [Rule 12: Let only one worker move the money](https://johnkaranja.com/guide/one-writer/)
[PreviousDecide what happens when things break](https://johnkaranja.com/guide/choose-how-to-fail/) [NextAll or nothing: no half-done changes](https://johnkaranja.com/guide/all-or-nothing/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 05: All or nothing: no half-done changes
Source: https://johnkaranja.com/guide/all-or-nothing/

The field guide · rule 05 of 16
## All or nothing: no half-done changes
A change should happen completely or not at all, never halfway.
### What it means
Some changes have several steps. If the system stops in the middle, you are left with a half-done change, which is often worse than no change. Make each change all or nothing. Databases do this with transactions. Files do it by writing a new copy and swapping it in. Releases do it by building the new version beside the old one and switching only when it works.
### What goes wrong without it
Money leaves one account, the server restarts, and the money never arrives in the other.
### How I build it
From systems I build and run.
- My AI agent system writes each file to a temporary copy and swaps it in, in one step, so a crash never leaves a half-written file.
- In my chain-intelligence service, each database change and the record that it ran are saved together, in one step.
- Space.ke releases are built in a separate folder and checked before the switch. If the site or its back end fails the check, both go back to the last version.
### Ask your team
- If the server stops halfway through a payment, what is left behind?
- Can a release be undone in one step?
- Are related database changes saved together, or not at all?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review traces each multi-step change and marks every place where a crash could leave it half done.
[Request a review](https://johnkaranja.com/book/request/?path=lead) [The offer: Architecture review or handover check](https://johnkaranja.com/book/offer/?path=lead) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=lead)
### Related rules
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
- [Rule 15: Ship only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
[PreviousMake actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/) [NextStore money in whole numbers, and make the books balance](https://johnkaranja.com/guide/money-in-whole-numbers/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 06: Store money in whole numbers, and make the books balance
Source: https://johnkaranja.com/guide/money-in-whole-numbers/

The field guide · rule 06 of 16
## Store money in whole numbers, and make the books balance
Never store money in a way that rounds. Use whole cents, and write down the rule that must always hold.
### What it means
Computers store some decimal numbers with tiny rounding errors, and these add up. Store money as whole numbers of the smallest unit, such as cents or satoshis, or use exact decimals. Then write down the rule that must always be true, such as "money in equals money out plus what is still owed", and have the system check it automatically.
### What goes wrong without it
Small rounding errors pile up until the totals no longer match the bank, and nobody can say where the difference went.
### How I build it
From systems I build and run.
- My finance back-office stores amounts in cents, checks that every entry balances, and refuses negative amounts. Closed months are locked, so no script can quietly change figures that were already filed.
- In my mining pool, the payouts in each block must add up exactly to the block reward, and a test proves that not a single satoshi is created or lost.
- My chain-intelligence service uses exact decimals for every money sum.
### Ask your team
- Is money stored in whole units or exact decimals, never in a way that rounds?
- Is there a written rule that the totals must always meet?
- Does anything check that rule automatically?
A "no" or "not sure" is worth a closer look.
### How a review checks this
The payments check reconciles a sample of records against their source and tests the balance rule itself.
[Request a review](https://johnkaranja.com/book/request/?path=pay) [The offer: Payments and ledger integrity check](https://johnkaranja.com/book/offer/?path=pay) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=pay)
### Related rules
- [Rule 01: Keep each fact in one place](https://johnkaranja.com/guide/one-source-of-truth/)
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
[PreviousAll or nothing: no half-done changes](https://johnkaranja.com/guide/all-or-nothing/) [NextGive each part only the power it needs](https://johnkaranja.com/guide/least-power/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 07: Give each part only the power it needs
Source: https://johnkaranja.com/guide/least-power/

The field guide · rule 07 of 16
## Give each part only the power it needs
Keep keys out of the code, and design so that one broken part cannot do much damage.
### What it means
Give every part of a system the smallest set of powers it needs to do its job. Keep passwords and keys out of the code. Then, if one part is broken into, the damage stays small. The parts that face the internet should have no power to move money.
### What goes wrong without it
A website is hacked. Because the website holds the keys to the wallet, the money goes too.
### How I build it
From systems I build and run.
- My chain-intelligence service creates payment addresses from a public key only. The keys that can spend stay offline, so a hacked server cannot move funds.
- In my AI agent system, people sign in with a password and a one-time code. The agents get limited access and see records with account and tax numbers removed.
- My background services each run as their own restricted user, and only accept connections from the machine they run on.
### Ask your team
- Could anyone outside your team still get in with an old key or account?
- If your web server were hacked, could it move money?
- Are passwords and keys kept out of the code?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review lists who and what holds each key and account, and what each one could do if it were misused.
[Request a review](https://johnkaranja.com/book/request/?path=lead) [The offer: Architecture review or handover check](https://johnkaranja.com/book/offer/?path=lead) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=lead)
### Related rules
- [Rule 09: Several simple guards beat one clever wall](https://johnkaranja.com/guide/layers-of-protection/)
- [Rule 08: Prove who is asking](https://johnkaranja.com/guide/prove-who-is-asking/)
[PreviousStore money in whole numbers, and make the books balance](https://johnkaranja.com/guide/money-in-whole-numbers/) [NextProve who is asking](https://johnkaranja.com/guide/prove-who-is-asking/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 08: Prove who is asking
Source: https://johnkaranja.com/guide/prove-who-is-asking/

The field guide · rule 08 of 16
## Prove who is asking
Every request should prove who sent it, and that it was not changed or sent again.
### What it means
A request arriving at your system should prove who sent it, that nobody changed it on the way, and that it is not an old request being sent again. Common tools are signed messages, one-time codes and timestamps. Secret checks should take the same time whether a guess is close or not, so attackers learn nothing from the timing.
### What goes wrong without it
Someone copies a valid request and sends it again an hour later, and the system acts on it twice.
### How I build it
From systems I build and run.
- People sign in to my chain-intelligence service by signing a one-time message with their wallet. The server checks it, then deletes it so it cannot be used again. There are no passwords at all.
- Services in my systems sign each request with a timestamp, and anything more than a few minutes old is refused.
- My language tutor checks its private-access cookie with a comparison that takes the same time for every guess.
### Ask your team
- Does every service check who is calling it?
- Would an old, copied request be refused?
- Do sign-in links and codes work only once?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review checks how each entry point knows who is calling, and tries an old request again to see if it is refused.
[Request a review](https://johnkaranja.com/book/request/?path=any) [The offer: Architecture review](https://johnkaranja.com/book/offer/) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=any)
### Related rules
- [Rule 07: Give each part only the power it needs](https://johnkaranja.com/guide/least-power/)
- [Rule 02: Check everything that comes in](https://johnkaranja.com/guide/check-what-comes-in/)
[PreviousGive each part only the power it needs](https://johnkaranja.com/guide/least-power/) [NextSeveral simple guards beat one clever wall](https://johnkaranja.com/guide/layers-of-protection/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 09: Several simple guards beat one clever wall
Source: https://johnkaranja.com/guide/layers-of-protection/

The field guide · rule 09 of 16
## Several simple guards beat one clever wall
No single check is perfect, so stack simple, separate guards. When one misses, the next one catches it.
### What it means
Every check has gaps. Instead of one clever defence, stack several simple ones that work separately from each other. If one fails, the next one catches the problem.
### What goes wrong without it
One spam filter fails, and fake sign-ups flood the system overnight.
### How I build it
From systems I build and run.
- The Space.ke site stops spam with a hidden trap field, a limit for each visitor, a robot check on sign-up and a check on where each request comes from.
- My AI agent system removes private data twice: once when an agent reads a record, and again just before any text is sent to an AI service. If the cleaning fails, nothing is sent.
- Business rules are checked in the code and again in the database, so a script that skips the code still meets the rule.
### Ask your team
- If your main check failed, what would catch the problem next?
- Are your most important rules also enforced in the database?
- Is private data removed before it leaves your system?
A "no" or "not sure" is worth a closer look.
### How a review checks this
For each serious risk, a review counts the separate guards in its way, and flags any risk that has only one.
[Request a review](https://johnkaranja.com/book/request/?path=any) [The offer: Architecture review](https://johnkaranja.com/book/offer/) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=any)
### Related rules
- [Rule 02: Check everything that comes in](https://johnkaranja.com/guide/check-what-comes-in/)
- [Rule 07: Give each part only the power it needs](https://johnkaranja.com/guide/least-power/)
[PreviousProve who is asking](https://johnkaranja.com/guide/prove-who-is-asking/) [NextExpect other services to fail](https://johnkaranja.com/guide/expect-failure/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 10: Expect other services to fail
Source: https://johnkaranja.com/guide/expect-failure/

The field guide · rule 10 of 16
## Expect other services to fail
Retry what is safe, pause what keeps failing, keep a second source, and never blindly resend money.
### What it means
Outside services fail. Retry the safe things, and wait a little longer each time. If a service keeps failing, stop calling it for a while. Keep a second source ready. Most important of all: never automatically retry something that may already have worked, such as sending money.
### What goes wrong without it
A payment provider is slow to answer. The system decides the payment failed and sends it again. Both payments go through.
### How I build it
From systems I build and run.
- My chain-intelligence service uses several blockchain connections in order of preference. One that keeps failing is skipped for a few minutes, then checked again.
- In my reward systems, a coin transfer is sent once only. If there is no answer, the result is marked "unknown", and a person checks the blockchain before anything else happens. A wrong "unknown" costs a check; a wrong "failed" costs a double payment.
- My research service fetches its sources at the same time, so it is only as slow as the slowest one.
### Ask your team
- When a payment times out, does the system know whether it went through?
- Does anything stop calling a service that keeps failing?
- Is there a second source for anything critical?
A "no" or "not sure" is worth a closer look.
### How a review checks this
The payments check follows what happens after a timeout, step by step, and marks any retry that could pay twice.
[Request a review](https://johnkaranja.com/book/request/?path=pay) [The offer: Payments and ledger integrity check](https://johnkaranja.com/book/offer/?path=pay) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=pay)
### Related rules
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
- [Rule 03: Decide what happens when things break](https://johnkaranja.com/guide/choose-how-to-fail/)
[PreviousSeveral simple guards beat one clever wall](https://johnkaranja.com/guide/layers-of-protection/) [NextOn a blockchain, wait until it is final](https://johnkaranja.com/guide/blockchain-final/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 11: On a blockchain, wait until it is final
Source: https://johnkaranja.com/guide/blockchain-final/

The field guide · rule 11 of 16
## On a blockchain, wait until it is final
The newest blocks can be replaced. Wait for confirmations, count each transaction once, and refuse old requests.
### What it means
Blockchains have their own ways of going wrong. The newest blocks can be replaced by others (engineers call this a reorg), so wait for enough confirmations before treating money as received. Make sure each transaction is counted once, and that a signed request cannot be sent again later.
### What goes wrong without it
A deposit is credited as soon as it appears. Its block is replaced, the deposit disappears, and the customer has already withdrawn the money.
### How I build it
From systems I build and run.
- My chain-intelligence service reads a little behind the newest block, replaces any saved block that the chain rewrites, and credits a payment only after enough confirmations. One transaction can only ever pay one order.
- My mining pool never trusts a miner's claimed result. It rebuilds the work and checks it itself.
- My trading software numbers its exchange requests in rising order, so an old request cannot be replayed.
### Ask your team
- How many confirmations do you wait for before you credit a deposit?
- What happens to a credit if its block is replaced?
- Can one transaction ever be counted twice?
A "no" or "not sure" is worth a closer look.
### How a review checks this
For products that touch a blockchain, the payments check covers confirmations, replaced blocks and double counting.
[Request a review](https://johnkaranja.com/book/request/?path=pay) [The offer: Payments and ledger integrity check](https://johnkaranja.com/book/offer/?path=pay) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=pay)
### Related rules
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
- [Rule 10: Expect other services to fail](https://johnkaranja.com/guide/expect-failure/)
[PreviousExpect other services to fail](https://johnkaranja.com/guide/expect-failure/) [NextLet only one worker move the money](https://johnkaranja.com/guide/one-writer/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 12: Let only one worker move the money
Source: https://johnkaranja.com/guide/one-writer/

The field guide · rule 12 of 16
## Let only one worker move the money
When several copies of a program run at once, decide which jobs may run in one place only.
### What it means
To serve more people, you run several copies of a program. But if every copy also runs the same background job, that job is done several times. Keep the parts that serve pages easy to copy, and let only one place run the jobs that move money. When two try at once, let the database decide who wins.
### What goes wrong without it
Two copies of the payment checker see the same deposit, and both credit it.
### How I build it
From systems I build and run.
- My chain-intelligence service uses every processor to show pages, but only one process checks payments.
- In my reward systems, a payout is claimed with one database step that works only if the payout is still waiting, so two staff can never pay the same request.
- My AI agent system locks shared files, so two jobs cannot overwrite each other.
### Ask your team
- If you started a second server, would any job run twice?
- Could two staff approve the same payout at the same moment?
- Which part breaks first if your number of users doubles?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review lists the jobs that must never run twice, and checks what stops them when the system grows.
[Request a review](https://johnkaranja.com/book/request/?path=lead) [The offer: Architecture review or handover check](https://johnkaranja.com/book/offer/?path=lead) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=lead)
### Related rules
- [Rule 04: Make actions safe to repeat](https://johnkaranja.com/guide/safe-to-repeat/)
- [Rule 01: Keep each fact in one place](https://johnkaranja.com/guide/one-source-of-truth/)
[PreviousOn a blockchain, wait until it is final](https://johnkaranja.com/guide/blockchain-final/) [NextKeep AI on a budget and on the facts](https://johnkaranja.com/guide/ai-on-a-budget/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 13: Keep AI on a budget and on the facts
Source: https://johnkaranja.com/guide/ai-on-a-budget/

The field guide · rule 13 of 16
## Keep AI on a budget and on the facts
Treat AI like any paid service that is sometimes wrong: cap the cost, give it checked facts, check its answers, and keep a person in charge.
### What it means
AI can do real work, but it costs money each time and it can be wrong with confidence. Send each task to the cheapest model that can do it. Cap the spending. Give it only checked facts to work from. Ask for answers in a fixed format, check them, and keep a person in charge of anything that matters, such as money or what you publish.
### What goes wrong without it
An AI assistant invents a price that is not on your site, and a customer holds you to it.
### How I build it
From systems I build and run.
- My AI agent system sends each task to a small, medium or large model depending on how hard it is, and refuses calls once the monthly cap is reached.
- The assistant on this site answers only from the published pages, and says so when the answer is not there.
- My language tutor may only use sentences that people have checked. Any word that is not from that checked set is flagged.
- My content tools check posts for private data, then wait for a person to approve them before anything is published.
### Ask your team
- Is there a spending cap on your AI use?
- Does your AI work only from sources you have approved?
- Does a person approve anything that moves money or goes public?
A "no" or "not sure" is worth a closer look.
### How a review checks this
The AI readiness review maps where the AI reads, what it may do, who checks it and what it costs, before a small trial.
[Request a review](https://johnkaranja.com/book/request/?path=ai) [The offer: AI readiness review](https://johnkaranja.com/book/offer/?path=ai) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=ai)
### Related rules
- [Rule 03: Decide what happens when things break](https://johnkaranja.com/guide/choose-how-to-fail/)
- [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
[PreviousLet only one worker move the money](https://johnkaranja.com/guide/one-writer/) [NextLet tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 14: Let tests decide when work is done
Source: https://johnkaranja.com/guide/tests-decide/

The field guide · rule 14 of 16
## Let tests decide when work is done
Agree what "correct" means as tests before you build, and for money, test the rule itself.
### What it means
Without agreed checks, "finished" is just an opinion. Write tests at the right levels: small ones for single pieces, bigger ones for pieces working together, and full runs through a real browser. For important logic, run the old and the new code on the same inputs and compare. For money, test the rule that must always hold, not just a few examples.
### What goes wrong without it
A change passes a quick look, goes live, and quietly breaks the refund flow.
### How I build it
From systems I build and run.
- My AI agent system runs its full test suite, type checks and a security check of its libraries before any change is shared.
- My chain-intelligence service has back-end tests, and browser tests that also check accessibility.
- In my mining pool, comparing the old and new code caught one miner being overpaid and another being underpaid. After the fix, a full test run matched every payout.
### Ask your team
- Do tests decide when a piece of work is done?
- Is your most important money rule tested directly?
- Do tests run automatically before every release?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review reads what your tests actually prove, and names the important behaviour that nothing tests yet.
[Request a review](https://johnkaranja.com/book/request/?path=team) [The offer: One-day hands-on workshop](https://johnkaranja.com/book/offer/?path=team) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=team)
### Related rules
- [Rule 15: Ship only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
- [Rule 06: Store money in whole numbers, and make the books balance](https://johnkaranja.com/guide/money-in-whole-numbers/)
[PreviousKeep AI on a budget and on the facts](https://johnkaranja.com/guide/ai-on-a-budget/) [NextShip only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 15: Ship only what was checked, and watch it run
Source: https://johnkaranja.com/guide/ship-safely/

The field guide · rule 15 of 16
## Ship only what was checked, and watch it run
Release exactly what was reviewed, check it after every release, keep a way back, and hear about problems before your users do.
### What it means
Releasing is part of the work, not an afterthought. Ship only the version that was reviewed. Check the system's health after every release. Keep a quick way back to the last version. Set up monitoring, so you hear about problems before your customers do.
### What goes wrong without it
A fix made directly on the server is overwritten by the next release, and the old bug comes back.
### How I build it
From systems I build and run.
- My chain-intelligence service releases only the exact version that was approved, and a person confirms each release.
- My AI agent system has quality gates that only let things stay the same or improve, and checks that what is running matches the code.
- Space.ke has a daily check that the site is up, that the live version matches the main code, and that its data is fresh.
### Ask your team
- Can you release a small change and undo it the same day?
- Is what is live exactly what was reviewed?
- Would you hear about an outage before a customer tells you?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review follows one change from a developer's machine to live, and marks each step where it could go wrong unseen.
[Request a review](https://johnkaranja.com/book/request/?path=lead) [The offer: Architecture review or handover check](https://johnkaranja.com/book/offer/?path=lead) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=lead)
### Related rules
- [Rule 05: All or nothing: no half-done changes](https://johnkaranja.com/guide/all-or-nothing/)
- [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
[PreviousLet tests decide when work is done](https://johnkaranja.com/guide/tests-decide/) [NextFix the cause, not just the symptom](https://johnkaranja.com/guide/fix-the-cause/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# Field guide rule 16: Fix the cause, not just the symptom
Source: https://johnkaranja.com/guide/fix-the-cause/

The field guide · rule 16 of 16
## Fix the cause, not just the symptom
Every system has bad days. What counts is a calm account of what happened, and a rule that stops it happening again.
### What it means
Every system has incidents. Write a short, calm account: what happened, how you noticed, how you fixed it, and the rule you added so that kind of failure cannot happen again. Fixing only the one case leaves the door open for the next one.
### What goes wrong without it
A bug is patched in a hurry, nobody asks why it happened, and a cousin of the same bug comes back a month later.
### How I build it
From systems I build and run.
- In one of my systems, a missing exchange rate quietly fell back to a wrong default, and some payouts went out too large. The fix: one part owns the rate, there is no fallback, and if the rate is missing, payouts stop.
- A data reader once kept moving forward while quietly failing to save. It now raises an alarm after a few failed saves, because a hidden error must never look like success.
- Orders that a trading bot had lost track of once stalled it for days. The fix replaces stale orders safely and limits retries.
### Ask your team
- Do you write down what happened after each incident?
- Does each fix include a guard against that kind of failure?
- Do the same problems keep coming back?
A "no" or "not sure" is worth a closer look.
### How a review checks this
A review asks for your last few incidents, and checks whether each fix closed the whole class of problem or only the one case.
[Request a review](https://johnkaranja.com/book/request/?path=lead) [The offer: Architecture review or handover check](https://johnkaranja.com/book/offer/?path=lead) [Check your system in one minute](https://johnkaranja.com/book/questions/?path=lead)
### Related rules
- [Rule 03: Decide what happens when things break](https://johnkaranja.com/guide/choose-how-to-fail/)
- [Rule 14: Let tests decide when work is done](https://johnkaranja.com/guide/tests-decide/)
[PreviousShip only what was checked, and watch it run](https://johnkaranja.com/guide/ship-safely/) [Back toAll 16 rules](https://johnkaranja.com/guide/)
John Wainaina Karanja · product and systems lead · UTC+3 · [info@johnkaranja.com](mailto:info@johnkaranja.com) · [johnkaranja.com/book](https://johnkaranja.com/book/) · [Privacy](https://johnkaranja.com/privacy/)

# All offers on one page
Source: https://johnkaranja.com/offers/

[](https://johnkaranja.com/book/)
Fixed-price reviews
## Know what to fix first
Five fixed-price reviews and a one-day workshop, for founders, teams and investors. You get evidence, a clear plan and a call to go through it, before you spend more on building. Hire me for the follow-on work within 60 days and the full fee counts towards it.
### Architecture review
USD 2,450 fixed · 10 hours at USD 245 an hour · about 10 days
Find out where your system is sound, where it is fragile and what to change first. One application, the most important thing your users do in it, and the services it connects to.
You get
- A labelled diagram of the system as it is
- Findings, most important first, with evidence and what is still unknown
- A recommended design, with its pros and cons
- A short plan, in order, your team can act on
- A call to go through it, and one round of questions
Not included
Code changes, deployment, load or penetration testing, security certification.
Smaller or larger
Start smaller: a 90-minute working session on one question, USD 300, which counts towards the review. Go further: help building it, in stages you can review, priced after the review.
Checked against rules [01](https://johnkaranja.com/guide/one-source-of-truth/), [03](https://johnkaranja.com/guide/choose-how-to-fail/), [05](https://johnkaranja.com/guide/all-or-nothing/), [07](https://johnkaranja.com/guide/least-power/), [15](https://johnkaranja.com/guide/ship-safely/) of the [field guide](https://johnkaranja.com/guide/).
### Payments and ledger integrity check
USD 2,450 fixed · 10 hours at USD 245 an hour · about 14 days
Find where a payment could be lost, repeated or recorded wrongly. One payment or payout flow and its ledger trail, traced with a sample that has private details removed. No live payments.
You get
- A payment-state map
- Findings you can trace, and the evidence that is missing
- A list of failure cases to test
- Fixes in order, each with a "done when" check
- A call to go through it, and one round of questions
Not included
Financial audit, tax or accounting opinion, smart-contract audit, handling passwords or keys, moving funds or building the fixes.
Smaller or larger
Start smaller: a 90-minute working session on one flow, USD 300, which counts towards the check. Go further: the fix work, and monthly checking support if you want it, priced after the check.
Checked against rules [04](https://johnkaranja.com/guide/safe-to-repeat/), [06](https://johnkaranja.com/guide/money-in-whole-numbers/), [10](https://johnkaranja.com/guide/expect-failure/), [11](https://johnkaranja.com/guide/blockchain-final/), [12](https://johnkaranja.com/guide/one-writer/) of the [field guide](https://johnkaranja.com/guide/).
### AI readiness review
USD 2,450 fixed · 10 hours at USD 245 an hour · about 10 days
Find out if an AI workflow is ready for a small, limited trial, what to prove first, and how people stay in control when it goes wrong.
You get
- A short report that keeps evidence apart from guesses
- A map of the workflow and who approves what
- A trial plan: what counts as success, and when to stop
- Next steps, in order
- A call to go through it, and one round of questions
Not included
Training AI models, access to live systems, legal advice on data rights, or promises about accuracy or returns.
Smaller or larger
Start smaller: a fixed check of one workflow you already run, USD 1,000. Go further: a trial build, and monthly help from USD 5,000 a month (about ten hours a week) if you want it.
Checked against rules [13](https://johnkaranja.com/guide/ai-on-a-budget/), [03](https://johnkaranja.com/guide/choose-how-to-fail/), [09](https://johnkaranja.com/guide/layers-of-protection/), [14](https://johnkaranja.com/guide/tests-decide/) of the [field guide](https://johnkaranja.com/guide/).
### Architecture review or handover check
USD 2,450 fixed · 10 hours at USD 245 an hour · about 10 days
Before you hand me, or anyone, the keys: a clear account of how the product is built, who holds what, what breaks first, and a plan for the first 30 days.
You get
- A diagram of the system today, and a list of who has access
- Findings, riskiest first, with evidence and what is still unknown
- A plan for the first 30 days
- What a part-time technical lead would own, week by week
- A call to go through it, and one round of questions
Not included
Code changes during the review, security certification, hiring or employment terms.
Smaller or larger
Start smaller: a 90-minute working session on the decision in front of you, USD 300, which counts towards the review. Go further: a part-time technical lead, from USD 5,000 a month, about ten hours a week.
Checked against rules [01](https://johnkaranja.com/guide/one-source-of-truth/), [07](https://johnkaranja.com/guide/least-power/), [12](https://johnkaranja.com/guide/one-writer/), [15](https://johnkaranja.com/guide/ship-safely/), [16](https://johnkaranja.com/guide/fix-the-cause/) of the [field guide](https://johnkaranja.com/guide/).
### Technical due diligence
USD 4,500 fixed · a product with 1 to 2 developers · about 15 days
A clear account of the technical risks, open questions and handover problems before you buy, invest in or partner with a product. Larger codebases are priced separately.
You get
- A risk report, each point linked to its evidence
- Checked facts kept apart from seller claims and missing evidence
- Questions for the technical team
- Conditions to set before signing, and a handover outline
- A call to go through it, and one round of questions
Not included
Valuation, investment advice, legal ownership opinion, financial audit, a complete code or security audit.
Smaller or larger
Start smaller: a 90-minute working session on the deal in front of you, USD 300, which counts towards the diligence. Go further: after the deal, a technical plan for the first 90 days, priced separately.
Checked against rules [07](https://johnkaranja.com/guide/least-power/), [01](https://johnkaranja.com/guide/one-source-of-truth/), [14](https://johnkaranja.com/guide/tests-decide/), [15](https://johnkaranja.com/guide/ship-safely/) of the [field guide](https://johnkaranja.com/guide/).
### One-day hands-on workshop
USD 2,000 fixed · one day, up to 10 people, online or on site
Your team builds one AI-agent workflow end to end on its own code, and leaves with rules, a review checklist and a plan.
You get
- A short call first to choose the task and the code
- A full day, hands-on, on your own code
- A shared rule file and a review checklist
- A one-page plan for the next month
- One follow-up call two weeks later
Not included
Building your product, tool licences, model training or certification.
Smaller or larger
Start smaller: a 90-minute briefing for leaders, USD 300, which counts towards the workshop. Go further: 4 to 12 weeks of coaching for the team, priced per team.
Checked against rules [13](https://johnkaranja.com/guide/ai-on-a-budget/), [14](https://johnkaranja.com/guide/tests-decide/), [15](https://johnkaranja.com/guide/ship-safely/), [16](https://johnkaranja.com/guide/fix-the-cause/) of the [field guide](https://johnkaranja.com/guide/).
### How it works
- Tell me what the system does and the decision you need to make.
- We agree the scope, the materials and read-only access in writing. Nothing starts before that.
- I review, then we go through the findings on a call.
- Build work is priced separately, in stages you can stop after.
[Request a review](https://johnkaranja.com/book/request/)
[Back to the book](https://johnkaranja.com/book/) [info@johnkaranja.com](mailto:info@johnkaranja.com) Paid by USD invoice before the work starts, or through Upwork, which holds the payment until the work is done. Prices exclude any taxes that apply to you.

# The musical logo
Source: https://johnkaranja.com/score/

[](https://johnkaranja.com/)
My name, read as a score
## Qwainaina, played
qwainaina reads “cue Wainaina”. A cue is a musician's signal to start playing, and Wainaina is my middle name. The qwainaina wordmark is drawn like sheet music: repeat dots, round noteheads, thick and thin barlines. This page reads the logo as a score and plays it, live in your browser.
Tap any letter to hear just its notes.
— ready
Sound Kalimba Marimba Lantern synth Tempo 96 Groove on the repeat Loop
### The paired dots
Seven letters carry two stacked dots, the mark a repeat sign uses. Each pair plays as two quick high notes.
### The noteheads
Each filled teardrop is a notehead. Its height on the logo sets its pitch: the lower it sits, the lower it sounds.
### The repeat
The dots say "play it again", so the phrase plays twice. The second time, a bass line and a groove come in.
### The scale
A minor pentatonic: five notes that always sit well together. High dots against low heads sound like two thumbs on a kalimba, and the last A resolves home.
### The score, letter by letter
LetterDotsNoteheadsChord
[Back to the home page](https://johnkaranja.com/) [info@johnkaranja.com](mailto:info@johnkaranja.com) The sound is made in your browser. Nothing is recorded or stored.

# Privacy
Source: https://johnkaranja.com/privacy/

[](https://johnkaranja.com/book/) [Request a review](https://johnkaranja.com/book/request/)
Privacy · last changed 11 November 2026 (chat assistant added)
## What this site counts, and what it keeps
Short version: no cookies, no advertising, no third-party trackers or scripts. The site counts a few things on its own server so I can tell which pages help, and forgets them after 90 days. Questions to the chat assistant go to an AI service to be answered, and are not kept here.
### What is counted
- Which page of the book you turn to, and which edition you choose.
- The result of the five questions (for example "2 of 5"), never your individual answers.
- Whether you opened your email with a request (and which review it names), copied it, copied my address, or opened a sample report. Not what you wrote: the request goes only from your own email, if you send it.
- Which rule of the field guide you open from the book.
- A short tag from the link you followed, when the link carries one (for example a link I shared in a proposal).
Nothing is counted if your browser sends Global Privacy Control or Do Not Track.
### The server log
Like every web server, this one notes each request: the time, the page, the link you came from, your browser's name, and your network address with its last part blanked, so it points to a neighbourhood of addresses, not to you. The log is kept for 90 days and then deleted. It is not sold, shared or joined with anything else.
### The chat assistant
If you ask the assistant a question, your question and the chat so far are sent to an AI service I pay for, to write the answer. Email addresses and phone numbers are removed first. The service does not use them to train its models. This site keeps no copy of what you wrote: it counts only that a question was asked and what the answer cost. Answers come from this site's pages and can be wrong. Please don't share private details in the chat. Ask me for details at [info@johnkaranja.com](mailto:info@johnkaranja.com).
### What stays in your browser
If you choose light or dark, that choice is remembered in your browser. A link's tag, and your chat, are held only until you close the tab. Your answers to the five questions are never stored.
### When you write to me
Your email, and anything you share for a review, is used only to reply and to do the work we agree, and is kept as correspondence. Ask me what I hold about you, or to delete it, at [info@johnkaranja.com](mailto:info@johnkaranja.com).
John Wainaina Karanja · UTC+3 · [Back to the book](https://johnkaranja.com/book/)