I built a machine-readable UK Chart of Accounts for Python (because one didn’t exist)

Table Of Contents

  • What it does
  • Quick example
  • Why VAT treatments matter
  • The LLM use case
  • HMRC box mappings

If you’ve ever tried to build accounting software for the UK market, you’ve hit the same wall I did: there’s no clean, machine-readable UK Chart of Accounts available on PyPI.

US-centric ones exist. Plenty of them. But UK accounting has different categories, VAT treatments, and HMRC-specific codes that don’t map neatly onto American standards.

So rejoice UK accountants, I built one.

What it does

uk-chart-of-accounts is a Python library with 166 standard UK nominal codes – the numbered category system every UK business uses to classify transactions. Each code includes:

  • Account type with double-entry rules (does a debit increase or decrease this account?)
  • VAT treatment (standard 20%, reduced 5%, zero-rated, exempt, or outside scope)
  • HMRC box mappings (CT600, VAT Return, FPS/RTI, EPS, CIS)
  • Tags for searchable grouping (motor, payroll, premises, etc.)
  • Descriptions on complex codes explaining the nuances

Zero dependencies. Pure Python. Works with Python 3.10+.

Quick example

from uk_coa import ChartOfAccounts, VatRate

coa = ChartOfAccounts()

# Look up any nominal code
account = coa.get(7602)
account.name          # "Accountancy Fees"
account.vat           # VatRate.STANDARD
account.vat_rate_pct  # 0.20
account.debit_increase  # True

# Search
coa.search("insurance")       # All accounts with "insurance" in the name
coa.by_vat(VatRate.EXEMPT)    # All VAT-exempt accounts
coa.by_tag("motor")           # All motor-related accounts

# Export for LLM prompts
context = coa.to_prompt_context()

Why VAT treatments matter

💡 Why VAT treatments matter

Getting this wrong means incorrect VAT returns. This library has every code’s VAT treatment pre-set, including nuances like residential vs. commercial rent.

Different expenses have different treatments:

Treatment Rate Examples
Standard 20% Most business expenses
Reduced 5% Domestic energy
Zero-rated 0% Books, children’s clothes
Exempt – Insurance, bank charges, Royal Mail postage
Outside scope – Wages, taxes, depreciation

This is the part most non-UK developers get wrong. UK VAT isn’t just “add 20%”.

The LLM use case

If you’re building AI-powered bookkeeping tools, the to_prompt_context() method formats the entire chart as structured text you can inject into an LLM prompt:

# Feed the chart to an LLM for transaction categorisation
context = coa.to_prompt_context(types=[AccountType.OVERHEAD])
prompt = f"""Given this chart of accounts:
{context}

Categorise this transaction: "TESCO 15.40 GBP"
"""

This gives the model the full code structure, names, and VAT treatments without you having to maintain prompt templates.

HMRC box mappings

Each code references the HMRC form and box it feeds into:

corp_tax = coa.get(2110)
corp_tax.hmrc_box  # "CT600 Box 86"

entertainment = coa.get(7403)
entertainment.hmrc_box  # "CT600 Box 46"
entertainment.description
# "VAT on business entertainment is blocked from input tax
#  recovery (HMRC VAT Notice 700/65). Disallowable for
#  corporation tax - must be added back on CT600."

Mappings cover CT600, VAT Return (Boxes 1-9), FPS/RTI, EPS, and CIS returns.

Install

pip install uk-chart-of-accounts

Background

I’m a finance professional who builds AI tools for UK accounting. This library came from extracting the reference data layer of a larger bookkeeping automation project. The codes, VAT treatments, and HMRC mappings are standard public knowledge – I’ve just packaged them in a way that’s actually usable in code.

Star the repo or open a PR

GitHub logo

billkhiz-bit
/
uk-chart-of-accounts

Machine-readable UK Chart of Accounts for Python. 166 nominal codes with VAT treatments and HMRC mappings.

uk-chart-of-accounts

Machine-readable UK Chart of Accounts for Python. 166 standard nominal codes with account types, VAT treatments, and HMRC box mappings.

Install

pip install uk-chart-of-accounts

Quick start

from uk_coa import ChartOfAccounts, AccountType, VatRate
coa = ChartOfAccounts()

# Look up by code
account = coa.get(7602)
account.name          # "Accountancy Fees"
account.type          # AccountType.OVERHEAD
account.vat           # VatRate.STANDARD
account.vat_rate_pct  # 0.20
account.debit_increase  # True (expenses increase on debit side)

# Search
coa.search("insurance")           # All accounts with "insurance" in the name
coa.by_type(AccountType.INCOME)   # All income accounts
coa.by_vat(VatRate.EXEMPT)        # All VAT-exempt accounts
coa.by_tag("motor")               # All motor-related accounts
coa.code_range(7000, 7012)        # Payroll overheads

# Convenience
coa.expenses()                    

…

India’s 3-Hour Deepfake Deadline Puts Evidence and Investigators at Risk

Analyzing the impact of deepfake regulation on biometric workflows

The news of India’s 3-hour deepfake takedown deadline is a massive stress test for computer vision (CV) engineers and biometric developers. When the response window is that tight, you aren’t just building a feature; you’re building a race against a clock that doesn’t care about false positives or forensic integrity. For those of us in the facial comparison space, this regulation creates a significant technical hurdle: how do you maintain accuracy when the law mandates speed over verification?

For developers working in biometrics, this regulation triggers a cascade of architectural problems. If a platform is forced to automate removals within 180 minutes, the first casualty is explainable AI. Most forensic investigators—the ones trying to close cases by comparing side-by-side evidence—rely on specific metrics like Euclidean distance analysis between face embeddings. When a law mandates a “nuke first” approach, the data required to verify identities or prove a deepfake’s origin is often wiped before an investigator can even initialize their analysis environment.

The Technical Collision: Comparison vs. Surveillance

There is a critical distinction that regulators frequently miss, and it’s one we emphasize at CaraComp: the difference between facial recognition (scanning crowds) and facial comparison (analyzing specific photos for a case).

Most enterprise-grade comparison tools use Euclidean distance—calculating the mathematical “gap” between facial landmarks in a multi-dimensional vector space. For a solo private investigator or a developer building forensic tools, this is the gold standard for building court-ready evidence. However, when global regulations like India’s IT Rules 2026 or the EU’s recent bans are drafted with broad, non-technical language, they risk grouping 1:1 forensic comparison tools under the same “high-risk” umbrella as mass surveillance systems.

From a deployment standpoint, this means developers may need to architect their systems to prioritize local processing. By keeping the comparison engine local rather than cloud-dependent, investigators can ensure their legitimate case analysis isn’t flagged or throttled by platform-level automated moderation.

The Erasure of the Forensic Hash

When a platform deletes synthetic content within three hours, it usually clears the associated metadata and forensic hashes that investigators use to track the spread of a deepfake. For developers, this means the API hooks used to analyze or archive public data are becoming increasingly brittle.

If we want to build tools that actually assist in insurance fraud detection or OSINT, we need detection frameworks that produce admissible evidence. A binary “True/False” result from a black-box model is useless in a legal context. We need the raw Euclidean metrics. We need to show exactly why two faces are a match.

Why Technical Access Matters for Evidence

One of the biggest risks in this regulatory landscape is that “truth” becomes a premium service. If enterprise tools costing $1,800/year are the only ones with the legal teams to navigate these rules, solo investigators and small firms are left in the dark. At CaraComp, we’ve focused on making the same Euclidean distance analysis used by federal agencies accessible for $29/mo. This isn’t just about price; it’s about ensuring that the technical tools required to debunk deepfakes aren’t restricted to those with massive budgets.

As developers, we have to start asking: How do we build “preservation-first” architectures that can survive a three-hour takedown window without compromising the evidence chain?

What technical safeguards can we implement in our computer vision pipelines to ensure that forensic comparison data is preserved even when the source material is purged from public platforms?

I Built a Free AI Sleep Tracker as a PWA — No App Store Needed

The Problem

Most sleep tracking apps cost $30-60/year, require app store downloads, and upload your personal sleep data to the cloud. I wanted something simpler.

So I built OohSleep — a free Progressive Web App that tracks your sleep, detects snoring with AI, and helps you fall asleep with ambient sounds and breathing exercises.

What It Does

  • 🎤 AI Snoring Detection — Uses the Web Audio API and MediaRecorder to listen for snoring patterns during sleep
  • 🎵 8 Sleep Sounds — Rain, ocean waves, thunder, campfire, wind, forest stream, crickets, and snow — all mixable
  • 🫁 5 Breathing Exercises — 4-7-8, Box Breathing, Belly Breathing, Alternate Nostril, and Physiological Sigh with guided animations
  • 📊 Sleep Reports — Track duration, quality score, and sound events over time
  • 📅 Sleep Calendar — Visual history with daily and weekly views

Tech Stack

No frameworks, no backend, no database. Just:

  • Vanilla HTML/CSS/JS
  • Web Audio API for sound mixing, playback, and audio analysis
  • MediaRecorder API for recording sleep audio and detecting snoring
  • Service Worker for full offline support
  • LocalStorage / IndexedDB for on-device data storage
  • PWA Manifest for cross-platform installation

Why PWA?

A Progressive Web App was the perfect fit:

  1. Cross-platform — Works on iOS, Android, Windows, Mac
  2. No app store — No review process, no 30% cut, instant updates
  3. Offline first — Works without internet after first visit
  4. Privacy by design — No server means no data collection

How Snoring Detection Works

The snoring detection uses the Web Audio API AnalyserNode to process microphone input in real-time. It captures audio via getUserMedia, runs FFT analysis to get frequency data, identifies characteristic snoring patterns (low-frequency rhythmic bursts), and uses MediaRecorder to save audio clips when snoring is detected.

Sound Mixing

Users can layer multiple ambient sounds simultaneously. Each sound has independent volume control through Web Audio API gain nodes, allowing custom sound environments for sleep.

Business Model

  • Free tier — Basic sleep tracking, timer, limited sounds, 7-day history
  • Premium $14.99/year — AI analysis, snoring detection, unlimited sounds, full history

Try It

👉 https://oohsleep.com

Open it on your phone, install it to your home screen, and try it tonight.

What technical challenges have you faced building PWAs? Let me know in the comments!

What Does a RAG Pipeline for Cypress Actually Look Like?

Running node query.js in the terminal showing the RAG pipeline retrieving the top three relevant chunks for

In the last post I asked whether the AI writing your Cypress tests actually knows your app. This one gets into what it looks like to give it that knowledge, with a real example I built locally.

The pattern is RAG, Retrieval-Augmented Generation. At its core it is straightforward. You index your app’s documents into a vector database, and at query time, the most relevant chunks are retrieved and passed to the AI as context. The AI generates a response grounded in your actual docs rather than guessing.

What I Indexed for Sauce Demo
I used Sauce Demo as my test app and created three docs:

  • An API spec covering login, inventory, cart, and checkout endpoints
  • A component doc with exact CSS selectors for every page
  • A bug history doc covering known failure scenarios like locked out users, problem user add to cart issues, and checkout validation gaps

Not everything needs to be indexed. What actually moved the needle was the component selectors and the bug history. The AI stopped guessing at button labels and started working from real data.

The Pipeline
I used ChromaDB as the vector database and Google Gemini embeddings to index the docs. The script follows five simple steps:
// Load environment variables
// Set up Google Gemini embeddings
// Connect to ChromaDB
// Read and chunk your docs
// Embed and store each chunk

Querying the Index
Once indexed, when you need a test step, you query the index, pull the most relevant chunks, and feed them to the AI before cy.prompt() ever runs. It is a wrapper, not a native feature.
Here is what came back when I queried “user login with valid credentials”:
Chunk 1: Login API spec with username and password structure
Chunk 2: Exact CSS selectors for the login page
Chunk 3: Known bug history related to login and locked out user

The AI now had everything it needed. The right selectors. The right endpoints. The known failure scenarios. All retrieved automatically from the docs.

Running node query.js in the terminal showing the RAG pipeline retrieving the top three relevant chunks for

A couple of things worth knowing before you try this:

  • ChromaDB needs to run as a separate service before you index or query anything
  • The embedding model name matters. For Google Gemini the correct model is gemini-embedding-001
  • RAG is a pre-processing layer, not a direct injection into cy.prompt(). You need a wrapper to bridge the two

Still figuring out the best chunking strategy for API specs. If you have tackled this before I would love to know what worked for you.

Contained Chaos: A Prototyping Operating Model for the AI Era

Your enterprise has a prototyping problem. Not too little. Too much. Here’s how to channel it.

The Fire Just Got More Fuel

Claude just announced 1 million token context. OpenAI keeps raising limits. Every month, the barrier to building something drops further. And the name of the fire this fuels isn’t “AI adoption.” It’s prototyping.

I’m deliberately not calling this vibe-coding. Vibe-coding is one leg of a much bigger thing. Prototyping is what happens when AI tools get good enough that anyone — not just engineers — can translate an idea into something that works. Product managers are building internal tools. Designers are generating functional front-ends. Business analysts are wiring up data pipelines. The ability to prototype is no longer a technical skill. It’s a social right.

And right now, people in your enterprise are prototyping like rats on cocaine.

I’ve seen it first-hand. Across a large enterprise with hundreds of engineering teams, I watched the prototyping volume go from “a few side projects” to “we genuinely don’t know how many AI-powered tools people have built” in under a year. Not because anyone approved it. Because the tools got good enough and the problems were obvious enough that people just… started building.

The Two Choices (Both Wrong)

As an enterprise, you’re staring at this and you have two instincts. Both are bad.

Choice 1: “If I don’t look, it’s not there.”

The Ostrich. Head in the sand. Let people do whatever they want. Meanwhile, someone in a corner of your organisation has already solved a million-dollar problem and can’t ship it because the PO told them the Jira ticket is the priority. Someone else, knowingly or unknowingly, just published confidential customer data to a public API because the prototype needed “real data to feel real.”

You didn’t see it. So it didn’t happen. Until it did.

Choice 2: “I see you. All of you. All the time.”

The Empire. Lock it down. Approved tools lists. Usage policies. Mandatory reviews. Kill every unsanctioned experiment before the ideas even seed. Congratulations — you’ve eliminated the security risk and the innovation at the same time. The Force is strong with governance, but the Rebellion has better ideas.

I watched an organisation do exactly this. They sent a company-wide email banning all “unapproved AI tool usage.” Within a week, the same engineers were using the same tools — they’d just stopped talking about it. The prototyping didn’t stop. The visibility did.

The Third Way

Is there a path where you channel this energy instead of ignoring it or crushing it? Where you turn contained chaos into enterprise value?

Yes. But before you say “you’re a genius” — let’s make sure you actually need this. Let’s look at what you’ve probably already tried, and why it didn’t work.

What You’ve Already Done (And Why It Didn’t Work)

Hackathons.

Every enterprise’s first move. Put people in a room for a day, high adrenaline, end-of-day presentations, a few standouts, investment promises from leadership, applause.

Next morning: new dawn, new day, back to the same work.

Hackathons are top-down events dressed up as bottom-up innovation. Most organisations run them for AI adoption and awareness, not for sustained value creation. They reward speed over substance. They produce demos, not products. And there’s no path from “you won the hackathon” to “here’s a team and a budget.” Winning means a trophy, not traction.

The Death Star looked impressive too. Didn’t survive contact with a thermal exhaust port.

Announcements and policies.

“Please be careful using unauthorised AI tools. Here are our data protection policies.” Sent via email. Nobody reads it. The people who need it most are the ones who’ve already found their own tools and aren’t looking at their inbox for permission.

AI awareness events.

Expensive. Low retention. The people who attend are already interested. The people who need it don’t show up. I sat through one that cost more than a junior developer’s annual salary. Three months later, I asked ten people what they remembered from it. Nobody could name a single takeaway.

AI governance and adoption teams.

They exist somewhere in your org chart. Most people don’t know where. These teams do important work — tooling evaluation, risk assessment, vendor management — but they operate in the background. They’re not connected to the people actually building things. I once asked a developer if they knew their company had an AI governance team. “We have a what?”

None of these are wrong. They’re just incomplete. They address pieces of the problem but none of them answer the real question: how do you systematically absorb the prototyping energy and turn it into value?

The Prototyping Operating Model

Here’s the model. Three parts: the system, the team, and the infrastructure.

Part 1: The System

A rolling submission model with quarterly selection.

Not a one-day event. Not “submit your ideas by Friday.” A continuous, open pipeline where people prototype at their own pace and submit when they’re ready.

Why rolling? Because good ideas don’t arrive on schedule. The engineer who cracks a problem at 2am on a Tuesday shouldn’t have to wait for the next hackathon to show anyone. And people should be able to submit as many ideas as they want — the evaluation process filters, not the submission process.

The submission rule: prototypes only.

This is the critical filter. And it’s inspired by something Jeff Bezos understood early: the best way to evaluate an idea isn’t to read a pitch deck about it — it’s to use it.

Submissions are not ideas. If it’s just a sketch on a napkin, it’s too early — go build it first. Submissions are also not deployed projects. If it’s already running in production, you’ve skipped the process entirely and we need a different conversation.

A submission is a prototype: an idea translated to a minimum working level. It runs. It demonstrates the concept. It’s rough. That’s fine. But it exists.

What a submission looks like:

Every submission is a pull request. The PR description follows a standardised template:

# Prototype Submission

> **Submission Title:** AI-Powered Inventory Alert System
> **Submitter:** Alex Chen / @achen
> **Date:** 2026-02-14
> **Category:** ai-ml

## Problem Statement
Our regional warehouse network (12 locations) relies on manual stock checks
and static reorder thresholds to manage inventory across 8,400 SKUs.
Warehouse coordinators spend 2-3 hours daily reviewing spreadsheets and ERP
dashboards to identify items approaching stockout.

## Dollar Value Framing
- **Value type:** Cost saving
- **Estimate:** $680,000/year
  - Stockout reduction: 340 events/quarter x 60% reduction x $320 avg
    emergency freight premium = $261,120/year
  - Labor savings: 12 coordinators x 1.5 hrs/day saved x 250 days x
    $48/hr = $216,000/year
- **Confidence level:** Medium

## Working Prototype
- **Link:** github.com/achen/inventory-alert
- **Tech stack:** Python, scikit-learn, PostgreSQL, Slack SDK, Streamlit
- **How to run it:** `docker compose up` → load data → train → dashboard

## Effort So Far
- **Time invested:** ~60 hours over 5 weekends
- **People involved:** Alex Chen (ML), Dana Torres (warehouse ops, domain)
- **What was hardest:** Demand signal for promotional periods — model
  treated promo spikes as anomalies, not patterns.

## What's Needed to Graduate
- **Team size:** 2 engineers + 1 ops lead for 3 months
- **Budget:** ~$85,000
- **Key risks:** ERP API access may require 6-8 week security review

Notice the structure. Dollar value framing forces people to think about whether the problem is worth solving before they submit. Effort transparency shows skin in the game. Graduation requirements keep expectations realistic. This isn’t a wish list — it’s an engineering proposal.

Quarterly evaluation and selection.

Every quarter, the organising team reviews all submissions from that cycle. Each submission gets scored against five criteria:

Criterion Score What It Measures
Business Value /5 Real problem? Credible dollar framing?
Technical Feasibility /5 Can this actually reach production?
Resource Efficiency /5 Lean ask relative to value?
Strategic Alignment /5 Fits org priorities?
Innovation Factor /5 Novel approach or new-to-us?
Total /25

The scoring isn’t a beauty contest. It’s a structured way to compare apples to oranges — an ML inventory system against a meeting decision recorder against a compliance automation tool. Every evaluator fills in the same template. Comments are mandatory. The numbers create ranking; the comments create accountability.

From the scores, they select:

  • Top 5 to reward — public recognition, small prizes, visibility to leadership
  • Top 15 to invest — dedicated time, resources, or team allocation for the next cycle

The rest get documented feedback. Every submission gets a response. No idea goes into a void.

Graduation paths:

Every selected prototype gets one of four outcomes:

  1. Graduate — fund it, staff it, put it on a product roadmap. It’s real now.
  2. Iterate — promising but not ready. Gets another cycle with more support.
  3. Shelve — valuable concept, wrong timing. Archived with documentation. Can be resurrected.
  4. Kill — learned what we needed. Thank the team, archive the code, close the loop.

Every decision gets a graduation record:

# Graduation Decision

> **Submission:** AI-Powered Inventory Alert System
> **Cycle:** Q1-2026
> **Evaluation Score:** 21/25 (ranked 3rd of 42 submissions)

## Outcome: GRADUATE
Fund it, staff it, integrate into product roadmap.

## Reasoning
Strong dollar value framing backed by real backtesting data (78% of
stockout events flagged with 5-day lead time). Low resource ask relative
to projected $680K/year savings. Warehouse ops champion already lined up.
Primary risk (ERP API access) is a known 6-week process, not a blocker.

## Next Steps
- [ ] Assign product owner: Maria Gonzalez
- [ ] Allocate team: 2 engineers + 1 ops lead, 3 months
- [ ] Schedule kickoff by 2026-04-01
- [ ] Define MVP scope: pilot at 2 locations

The key: every path has closure. People know what happened and why. No prototype enters zombie state — alive enough to haunt you, dead enough to not ship.

Part 2: The Operating Team

Two groups make this work: a leadership team and an organising team.

The leadership team has one job: investment authority. They review the organising team’s recommendations, make funding decisions, and connect graduated prototypes to product roadmaps. They don’t evaluate submissions — that’s the organising team’s job. They make it possible for good ideas to actually become real things.

What they should do:

  • Take time to understand what people are trying to solve, not just what they built
  • Attend demo sessions, ask questions, show genuine interest
  • Move fast on graduation decisions — momentum kills if you wait too long

What they should not do:

  • Treat this as a checkbox exercise — people can tell when leadership is performing interest versus showing it
  • Sit on graduation decisions for weeks — the engineer who built the prototype on their weekends deserves a timely answer

The organising team is the engine. These aren’t managers. These are your rockstars — the people who are already respected across the organisation. A cross-functional mix: product, UX, engineering, data, security. They understand both the technical and the business side.

Think of them as the Jedi Council — except one that actually listens to people instead of dismissing Anakin’s concerns. The job is curation, not gatekeeping.

What they should do:

  • Review submissions with open minds — the best ideas often look weird at first
  • Group similar submissions together — if five people independently prototyped something similar, that’s a signal about a real problem, not a coincidence. Pay attention to that.
  • Connect people working on adjacent problems — facilitate the conversations that wouldn’t happen organically
  • Look for patterns in what’s being built — the aggregate tells you more than any individual submission
  • Build tooling that helps people prototype faster — shared components, design systems, API templates, even AI-powered extensions for common patterns
  • Maintain transparency — everyone can see what’s been submitted, what’s been selected, and why

What they should not do:

  • Gate-keep based on role or seniority — a business analyst’s prototype is as valid as a staff engineer’s
  • Reject ideas for being “too simple” — simple solutions to real problems are the most valuable kind

Part 3: The Infrastructure (It’s a GitHub Repo)

This is where I might sound opinionated, but hear me out.

You don’t need a platform. You don’t need a multi-tenant app with versioning, workflows, approval chains, and a React dashboard. You need a GitHub repository.

I know what you’re thinking: “GitHub? For managing enterprise innovation?” Yes. And here’s why.

The instinct is to build a tool first. A submissions portal. A review dashboard. An analytics layer. Three months and $200K later, you have a beautiful platform and zero submissions because nobody wants to learn another internal tool. I’ve seen this happen twice. Both times, the platform outlived the programme.

Git + GitHub gives you almost everything:

prototype-ops/
├── templates/
│   ├── submission-template.md      # What submitters fill in (the PR)
│   ├── evaluation-template.md      # How reviewers score (per submission)
│   └── graduation-template.md      # Decision record (graduate/iterate/shelve/kill)
├── submissions/                    # One branch per submission, merged PRs = archive
├── examples/
│   ├── example-submission-1.md     # AI-Powered Inventory Alert System
│   ├── example-submission-2.md     # Meeting Decision Recorder
│   └── example-submission-3.md     # Compliance Doc Generator
├── docs/
│   ├── guidelines.md               # Do's and don'ts, approved tools
│   ├── ai-tools-guide.md           # What AI tools the company offers + how to use
│   ├── problem-framing.md          # How to think about dollar value and effort
│   └── reference-problems.md       # Org-level problems leadership wants solved
└── dashboard/                      # Simple UI to visualise submissions
  • Submissions are pull requests. The prototype code lives in the PR. The description follows the submission template. Discussion happens in comments.
  • Decisions are recorded. Approved, rejected, needs iteration — it’s all in the PR history. Reviewers’ reasoning is captured.
  • Everything is in one place. No context-switching between a submissions portal, a Slack channel, an email thread, and a spreadsheet.
  • Transparency is built in. Anyone can browse open PRs to see what’s been submitted. No duplicate ideas because you can search before you submit.
  • Governance is native. Branch protection, required reviewers, templates — GitHub already has the workflow primitives.

The docs/ directory does the heavy lifting that policy emails never could. guidelines.md tells people what tools they can and can’t use — which naturally educates about shadow AI without a single compliance slide. ai-tools-guide.md shows people the power of tools the company already pays for — reducing the incentive to go rogue. problem-framing.md teaches people to think about dollar value and effort before they build — the best filter is self-filtering. reference-problems.md gives direction without being prescriptive: “here are problems leadership wants solved, if you’re looking for inspiration.”

And yes — you can add AI-powered extensions to the repo that automate submission review, evaluation grouping, status tracking, and reporting. The organising team doesn’t spend their time on mechanics. They spend it on judgment.

I’ve built a starter repo that any organisation can fork to bootstrap their prototyping operating model. It includes the submission templates, evaluation workflows, team manifest, and example submissions.

prototype-ops on GitHub — fork it, adapt the templates to your org, and you’re running by next quarter.

Why This Works (When Everything Else Didn’t)

The hackathon failed because it was an event. This is a system.

The governance policies failed because they said “don’t.” This says “do — but here.”

The awareness events failed because they were broadcasts. This is a conversation.

The AI adoption teams failed because they were invisible. This is visible by design — every submission, every decision, every outcome is public within the organisation.

And shadow AI? It doesn’t disappear. But it surfaces. When people have a legitimate channel for their prototyping energy — with clear guidelines, approved tools, and a path to recognition — the incentive to operate in the shadows drops dramatically. Not because you banned it. Because you made the alternative better.

Like the Rebel Alliance, you don’t win by building a bigger Death Star. You win by giving people something worth fighting for. A system that recognises their ideas, resources the good ones, and doesn’t waste their time with the rest. That’s the Prototyping Operating Model.

One Takeaway

Your people are already prototyping. They’re doing it on lunch breaks, on weekends, in the gaps between sprint tickets. The question isn’t whether to allow it. The question is whether you channel it into a system that creates value — or ignore it until someone publishes your customer data to a public repo.

Build the operating model. Stand up the team. Fork the repo. Start this quarter.

The dinosaurs are already out. The fence is already down. The only question left is whether you build Jurassic World with better containment — or keep pretending the park is still under control.

If your enterprise is drowning in unsanctioned prototypes — or worse, pretending they don’t exist — I’d like to hear how you’re handling it. What’s working? What spectacularly isn’t? And if you’ve tried hackathons and they didn’t stick, you already know why.

When Your AI Agent Has an Incident, Your Runbook Isn’t Ready

Your on-call engineer gets paged at 2am. The alert says your customer-facing AI agent is misbehaving — producing garbled outputs, possibly taking unintended actions, burning through tokens at ten times the expected rate. They open the runbook.

The runbook says: check the error rate, examine the trace, identify the failing component, roll back or patch.

None of that applies. The error rate is fine — the agent is executing successfully, it’s just doing the wrong thing. The “trace” is a wall of LLM completions with no clear causal structure. There’s no component to isolate because the failure is in reasoning, not in code. And rolling back the agent deployment doesn’t roll back whatever it already did.

This is the gap that most engineering teams discover at the worst possible time: 57% of organizations now have agents running in production, according to LangChain’s 2026 State of Agent Engineering report, but the same research found that quality (cited by 32% of respondents as their top blocker) and latency (20%) — not capability — are the primary barriers teams fight in production. Most of them don’t have runbooks written for how agents actually fail.

AI agent incident response is the set of practices, tools, and procedures for detecting, containing, investigating, and learning from failures in autonomous AI agent systems running in production. It differs from traditional software incident response in three fundamental ways: agent failures are often non-deterministic and non-reproducible, the blast radius of an agent incident extends across tool calls and external systems rather than a single service boundary, and the failure mode is frequently behavioral — the agent did something unexpected — rather than operational — the service went down. Effective agent incident response requires instrumentation, containment capability, and ownership structures that most SRE practices were not designed to provide.

Why does AI agent incident response differ from standard SRE?

The SRE toolkit was built for deterministic systems. Given the same input, a correctly-implemented service returns the same output. Incidents have causes you can identify, reproduce, and fix. Error rates measure something meaningful because errors are discrete, catchable events.

Agents break all three of these assumptions.

An agent that produced a wrong output at 14:32 may not produce the same wrong output if you replay the exact same session at 14:45. Model temperature, context window effects, subtle differences in retrieved data, and the inherent non-determinism of LLM sampling mean that replayable reproduction of agent failures is the exception, not the rule. Your on-call engineer cannot reliably reproduce what happened — which means standard debugging practices (write a test that replicates the failure, fix it, verify the test passes) don’t apply cleanly.

Error rates are the wrong metric. Most agent failures don’t look like errors. The API call succeeded. The session completed. The agent returned something. It just returned something wrong, or took an action outside its intended scope, or consumed 50x the expected token budget while doing it. Error rate monitoring tells you when your agent is down. It tells you nothing about whether your agent is doing the right thing.

The investigation workflow changes completely. When a service misbehaves, you look at logs, metrics, and the trace for the specific request that failed. When an agent misbehaves, you need the full execution record for the session — every LLM call, every tool invocation, every piece of data that entered the context window — because the failure may be distributed across a dozen steps rather than localized to a single function call. Without a session-level execution record that captures this graph, you’re reading tea leaves.

This is why the standard runbook breaks. It was written for incidents with discrete causes. Agent incidents often have diffuse causes that only become visible when you can see the entire session history at once.

Why is ownership of AI agent incidents so fragmented?

Here’s the question your runbook should answer and probably doesn’t: who owns the agent?

Not who built it. Who is responsible for its behavior in production — right now, when something is wrong, at 2am?

In most organizations, this is unclear in ways that don’t exist for traditional services. A microservice has an owning team, a deployment pipeline, a Slack channel for incidents, an on-call rotation. The ownership model for AI agents is younger and less established, and the fragmentation runs deep. The team that built the agent may not be the team that deployed it. The team that deployed it may not have authority over the model configuration. The compliance team may have opinions about agent behavior that nobody operationalized as policy. The security team discovered the agent is using a database credential they didn’t know existed.

When an agent incident hits, the first thirty minutes are often spent answering questions that should have been answered before the agent ever deployed: Who can change the agent’s configuration? Who can roll it back? Who has authority to shut it down entirely? Who is responsible for informing affected users?

The last question — who can shut it down — is particularly costly when the answer is unclear. An agent that’s behaving incorrectly in a way that affects customers needs to be stopped. If no one has a pre-established path to do that, the incident compounds while ownership is being negotiated. This is the specific failure mode that ends agent deployments: not the technical incident itself, but the organizational unreadiness to respond to it.

Organizations that have worked through this are explicit about agentic governance at the operational level — not just policy documents, but defined human ownership for every agent in production, with a RACI for incidents, a documented kill-switch procedure, and an on-call rotation that includes someone with authority to act.

What is the blast radius of an AI agent incident?

When a microservice throws a 500, the blast radius is bounded: the clients that called it got an error. They retry or they don’t. The failure is contained within a service boundary.

An agent’s blast radius doesn’t respect service boundaries. It extends to every system the agent had access to during the session — every API it called, every database it queried or wrote to, every external message it sent.

This matters for incident response because the alert is almost never the full picture. An alert that fires because an agent session consumed abnormal token volume tells you there was a problem. It doesn’t tell you what the agent did during those tokens. By the time the alert fired, the agent may have already written records to your CRM, sent messages to a customer, made API calls to external services, or processed sensitive data through systems that weren’t in scope for the original task.

Incident containment for agents has to start with a blast radius audit, not just service restoration. You need to know: what actions did the agent actually take before it was stopped? What data did it access? What external systems did it touch? What’s the status of every write operation it initiated?

Standard agent monitoring — token counts, latency, error rates — tells you the operational facts of your session. Production telemetry like this is the cost dashboard of your incident. What it doesn’t tell you is the action history: which records the agent read, which it modified, what it sent to which external system, and in what sequence. That’s the session execution record — the artifact that makes a blast radius audit possible. Without it, you’re left trying to reconstruct the agent’s activity from the scattered logs of every downstream system it touched — a forensic exercise that takes hours and frequently misses things.

What does a runbook for AI agents actually need?

A runbook written for agent incidents looks different from a service runbook in four specific ways.

Session trace first, error trace second. The first action in an agent incident is pulling the complete session record for the affected session — every LLM call, every tool invocation, token count per step, the full context window at each decision point. This is your primary diagnostic artifact. If you don’t have it, you’re working blind. Your monitoring setup needs to capture this proactively, before incidents happen, not reactively as a consequence of them.

Pre-established kill-switch. Before an agent deploys, the runbook must document exactly how to stop it — completely, immediately, for a specific session or for all sessions. This is not “submit a PR and redeploy.” It’s a procedure that can be executed in under five minutes by an on-call engineer who did not build the agent. Whether that’s a kill-switch policy, a circuit breaker configuration, a feature flag, or an emergency API call — document it, test it in staging, and make it executable without needing the original author.

Blast radius protocol. The runbook needs a documented procedure for auditing what the agent did before containment. This means a checklist of every external system the agent has write access to, a procedure for querying each system’s logs for activity from the affected session, and clear ownership for contacting those systems’ teams when needed. This protocol should be defined before the incident — not assembled under pressure during it.

Behavioral SLA, not just operational SLA. Traditional SLAs cover availability: the service must respond within X ms, error rate must stay below Y%. Agents need a second tier: behavioral SLAs that define what constitutes unacceptable agent behavior. Token spend above X per session. Output confidence below Y. Tool call to a system outside the agent’s defined scope. These behavioral thresholds are what trigger your incident response process before a customer complains — not after.

Most teams skip the behavioral SLA entirely because it requires answering a hard question: what, exactly, does your agent’s correct behavior look like? You can’t define acceptable without defining expected. The teams that survive their first agent incident are the ones that wrote down the answer before they needed it.

How Waxell handles this

How Waxell handles this: Waxell Observe instruments AI agents across any framework to capture the complete session execution graph — every LLM call, tool invocation, external API request, token cost, and timing data — stored as a durable execution record that exists before an incident happens, not assembled during it. When the 2am alert fires, your on-call engineer opens the session trace and sees exactly what the agent did, step by step, rather than piecing together scattered logs from downstream systems. Operational governance policies — circuit breakers, per-session token budgets, behavioral thresholds — give you the kill-switch mechanism that every runbook needs: a pre-configured rule that terminates the session automatically when a behavioral threshold is crossed, before the incident compounds. You define the behavioral SLA once at the governance layer; Waxell enforces it every session. The production telemetry layer surfaces session-level cost, latency, and behavioral metrics in real time — so the behavioral threshold breach is an alert you act on, not a customer complaint you explain.

To build the session-level visibility your runbook requires, get early access to Waxell.

Frequently Asked Questions

What is AI agent incident response?
AI agent incident response is the set of practices and procedures for detecting, containing, investigating, and learning from failures in autonomous AI agent systems running in production. It differs from traditional software incident response because agent failures are often non-deterministic (cannot be reliably reproduced), behavioral (the agent did something unexpected rather than throwing an error), and have a blast radius that extends across every system the agent had tool access to during the failing session — not just the service that generated an alert.

How is an AI agent incident different from a software service incident?
A software service incident usually involves a discrete failure you can identify, reproduce, and fix: a 500 error, a timeout, a null pointer. Agent incidents are often behavioral — the agent completed successfully but did something wrong. Error rates don’t capture them because the API calls succeeded. Blast radius is broader because agents have tool access to multiple external systems. And reproduction is difficult because agent behavior is non-deterministic; the same input may not produce the same failure twice. Standard runbook steps (trace the failing request, reproduce in staging, fix and verify) require significant adaptation for agent incidents.

What should be in a runbook for AI agents?
An agent runbook needs four elements that service runbooks typically don’t have: a procedure for pulling the complete session execution trace (not just the error log), a pre-established kill-switch procedure that can be executed in under five minutes without the original author, a blast radius audit protocol listing every external system the agent can write to and how to check their logs, and documented behavioral SLAs that define what constitutes unacceptable agent behavior — token spend per session, output confidence thresholds, tool scope violations — so incidents are triggered by policy breaches rather than customer complaints.

Why do AI agents get shut down after their first production incident?
The pattern is consistent across organizations: an agent hits a novel edge case, behaves unexpectedly, and causes some customer-visible harm. The incident response process is slow and disorganized because nobody defined incident ownership before the agent deployed. By the time the root cause is understood, confidence in the agent is gone and the deployment is rolled back indefinitely. The technical failure was recoverable. The organizational unreadiness wasn’t. Agents that survive their first production incident are almost always ones whose teams pre-defined ownership, kill-switch procedures, and behavioral SLAs before deploying — not as bureaucracy, but as operational prerequisites.

Sources

ADGM Tech Startup License: Self-Filed UAE Entity, $1,000, No Agent

In 2022, I set up an ADGM Tech Startup License by myself — no CSP, no agent. The registration fee was $1,000. It is now $1,500.

Most guides assume you will use a CSP (Corporate Service Provider), which adds $3,000–5,000 on top. I skipped it. It worked.

I also set up a UAE mainland company separately — different purpose, different process. That comparison is worth knowing. (I had a Dubai Virtual Working Program visa at the time and was planning to transfer sponsorship before it expired.)

Where ADGM fits among UAE options

Option Cost (approx.) Legal framework Notes
ADGM Tech Startup $1,500 + misc English common law Self-filing possible; Hub71 accepted companies must incorporate here
DIFC $10,000+ English common law Finance-focused, expensive
Dubai free zones (DMCC, IFZA etc.) $3,000–8,000 UAE civil law Wide variety, Dubai address
RAKEZ $1,500–5,500 UAE civil law Cheapest, less prestige
Mainland Varies UAE civil law CSP typically required

My reason for ADGM over Dubai free zones: cheapest English common law entity, and it keeps the Hub71 path open. You can apply to Hub71 before incorporating — no entity required to apply. If accepted, you incorporate in ADGM as part of joining, and the voucher covers CSP and other costs.

On RAKEZ: I have no personal experience. Based on research: mostly online incorporation with one UAE visit required for visa biometrics (doable in Dubai, not necessarily in RAK itself), banking accessible but may face more scrutiny at international banks, disputes go through RAK Commercial Court. Worth considering for cost-focused operational startups with no complex legal needs.

On mainland: I set one up to transfer my visa sponsorship before my nomad visa expired. Did not end up needing it, so I closed it. CSP was involved, banking through ADCB. The 2021 reform allowing 100% foreign ownership removed the local sponsor requirement — mainland is now a real option for foreign founders in most sectors.

What it costs

Item Cost
Registration fee $1,500 (was $1,000 in 2022)
Administrative / misc fees ~a few hundred USD
CSP fee (optional) $3,000–5,000
Registered office (required) Varies

If you come through Hub71, the voucher covers the CSP fee and other costs — see the Hub71 section below.

Before You File

1. Contact ADGM first. Before filing, reach out to confirm the Tech Startup License fits your business activities. The review is not strict, but getting confirmation upfront means you can proceed without uncertainty.

2. Registered office address. I needed a physical address before I could incorporate. (This was 2022 — current requirements may differ.) ADGM’s own co-working space had a wait, WeWork on Al Maryah had a wait. Other options existed — CloudSpace (as of 2022) and similar providers. More choices now that Al Reem Island is under ADGM jurisdiction (since December 2024).

Banking

I used Mashreq. Direct bank contact, dedicated officer assigned, documents submitted.

Wio Bank is the easiest option now — fully online, built for SMEs. A founder I know used it for a recent incorporation with no issues.

Hub71 route: FAB (First Abu Dhabi Bank) is a natural starting point — Hub71 has partnerships with FAB, ADCB, and ADNIC (insurance), among others.

Visa options

Main visa options for UAE residency as a founder:

  • Dubai Virtual Working Program visa (Virtual Working Visa): a few hundred dollars, proof of overseas income needed. Good for establishing residency before or during incorporation.
  • Company-sponsored visa: once the ADGM entity is set up, it can sponsor your visa.
  • Golden Visa (10-year): several pathways — Hub71 participation, qualifying profession/salary threshold, or real estate investment above AED 2M.

Hub71: Apply Before or After Incorporating?

Hub71 (hub71.com) is Abu Dhabi’s startup program backed by Mubadala and G42 — office space, funding access, and corporate partnerships for accepted companies. If accepted, the voucher covers incorporation, legal, accounting, and other operational costs.

You do not need to incorporate before applying — Hub71 accepts applications before you have an entity. But admission takes months, so waiting on a decision can delay operations by half a year or more.

If you incorporate first, the $1,500 registration fee is self-funded. But the Hub71 voucher still applies to accounting, legal, office costs, and other operational expenses — not just incorporation. Incorporating first does not make Hub71 pointless.

The practical split:

  • Early stage, time to spare: apply first (free). If accepted, the voucher covers incorporation plus operational costs. If not, self-file for $1,500.
  • Already moving: incorporate now and apply in parallel. If accepted, use the voucher for accounting, legal, and office expenses.

If your startup fits their focus areas (AI, deep tech, fintech, climate), applying is worth doing regardless of where you are in the process.

One additional angle for 2026: the security situation around Abu Dhabi has reduced inbound interest from some international founders. If that continues, Hub71’s applicant pool may thin — which could improve odds for those applying now.

What has changed since 2022

  • Fee: $1,000 → $1,500
  • Office options: Al Reem Island under ADGM — more eligible co-working spaces
  • Mainland: 100% foreign ownership now standard in most sectors
  • Banking: Wio Bank now available, simplest for new incorporations
  • Document prep: AI tools make business plans and constitutional docs much faster

Self-filing still works. The process is more accessible now than it was.

Si aun no has leido Street-Smart Coding, te dejo uno de los reviews: “Está escrito desde la experiencia. Es decir, no te dice cómo hay que hacer las cosas, sino cómo aprendió personalmente cómo hay que hacer las cosas.”

baltasarq profile

SD Times News Digest: Sonar, Nutrient, Outsystems — April 1, 2026

Sonar releases tools to verify code in agentic development Following the recent launch of Sonar’s framework for software development in the age of AI, the Agent Centric Development Cycle,  the company has announced the open beta of three new products to autonomously verify code in agent-driven development. AI agent coding are reinventing the way software … continue reading

The post SD Times News Digest: Sonar, Nutrient, Outsystems — April 1, 2026 appeared first on SD Times.