DEV Community: Osama Alghanmi

You Learn Faster When You Tell AI What You Already Know

Osama Alghanmi — Sat, 07 Mar 2026 03:17:32 +0000

Most people ask AI to explain things. Fewer people ask AI to explain things to them specifically.

Every concept has a cousin

State machines were confusing to me until I recognized I'd been building them manually for years, just without the name. Event sourcing clicked the moment someone described it as a git log for your data. These connections didn't happen by accident. Someone knew what I already understood and found the bridge.

AI can do this reliably, but only if you tell it where to start.

"Explain WebSockets" returns a definition. "Explain WebSockets to someone who understands HTTP request-response, specifically what breaks down when you need the server to push data without the client asking first," returns something you can actually use. The second question works because it gives AI a place to stand. It knows where you are. It doesn't have to guess.

This is how learning has always worked. New information sticks when it attaches to something already in your head. AI is unusually good at finding that attachment point across domains you'd never encounter side by side otherwise. It can connect your SQL knowledge to MongoDB aggregation, your OOP background to functional programming, your REST intuition to the specific friction GraphQL was designed to solve. But it needs your reference point to know which connection to draw.

The instinct that works against you

When learning something new, there's a pull toward beginner mode. You try to receive information fresh, as if your existing knowledge might contaminate it. Backend developers learning React sometimes treat state management as a new concept, rather than recognizing that they've been thinking about state for years in a different context.

Your existing models aren't contaminated. They're the reason new explanations stick. A backend developer who says: "I understand data flow and separation of concerns; show me how React handles both" will outpace someone who starts from scratch and works through the basics without that anchor.

Before asking AI to explain something, it's worth spending ten seconds on: what do I already know that this resembles? What problem does this thing solve that I've encountered before in a different form? The answer to either of those shapes a much better question.

It compounds

Once you establish a reference point, each follow-up question builds on it. You're not accumulating disconnected facts. You're extending an existing map.

People who seem to learn new technologies fast aren't processing information faster. They're anchoring better. Each new concept attaches to the previous one, which attaches to something before that. The reference point at the start of a learning session determines how much of the rest actually lands.

AI accelerates this by traversing domains in a single conversation. You can go from "I understand X" to a working mental model of something three conceptual steps away, without having to read three textbooks first. The catch is that the conversation has to start somewhere concrete. It's best when you have a knowledge repository that the LLM can pull from and use as a reference point.

We Need an Emission Test for AI

Osama Alghanmi — Sun, 01 Mar 2026 10:58:23 +0000

We test cars for emissions before they're allowed on the road. We rate appliances for energy efficiency. We slap labels on buildings telling you how much power they consume per square meter.

AI agents get none of this. No one asks how many tokens a system burned to answer a yes-or-no question.

Invisible Waste

Every token an LLM generates costs energy. Real electricity, real cooling, real hardware deprecation. A model that generates 2,000 tokens of preamble, caveats, and filler to deliver 40 tokens of actual information is producing waste. Physical, measurable, environmental waste.

Nobody's measuring it. We're in the "leaded gasoline" era of AI. The technology works, people love it, and the externalities are completely unpriced.

What Would This Look Like

A standardized benchmark for efficiency, not accuracy. Given a set of tasks with known correct answers, how many tokens does the system consume to get there?

Four metrics:

1. Token Efficiency Ratio (TER)

TER = useful_output_tokens / total_tokens_generated

A system that generates 500 tokens but only 80 carry actual information has a TER of 0.16. That's an F rating.

2. Task Completion Cost (TCC)

How many tokens (input + output) does the agent consume to complete a well-defined task? Summarize this document. Fix this bug. Answer this question. Two systems that both produce the correct answer are not equal if one uses 10x as many tokens.

3. Retry and Exploration Overhead

Agentic systems are the worst offenders. An agent that tries 5 wrong approaches before stumbling on the right one might "work," but it consumes 5x as many resources as one that reasons the first time correctly.

4. Conversation Waste Index

In multi-turn interactions, how much of the conversation is the AI repeating itself, restating the question, or generating text that the user already knows? The equivalent of an engine idling in traffic. Burning fuel, going nowhere.

The Numbers

ChatGPT alone has 900 million weekly active users. Add Gemini, Claude, Copilot, and the rest, and the real number is well over a billion. If each interaction costs an average of 500 unnecessary tokens, that's 500 billion tokens wasted per week. At roughly 0.001 kWh per 1,000 tokens (a conservative estimate for inference), that's 500,000 kWh per week in pure waste. Enough to power about 50,000 homes

Agentic AI will multiply this by orders of magnitude. Systems that run autonomously, calling tools, spawning sub-agents, looping through retries. An agent that runs for 10 minutes, burning tokens in a loop, wastes more than your money. It wastes shared atmosphere.

Where the Analogy Holds and Where It Breaks

Cars produce CO2 as a byproduct of moving you from A to B. AI tokens produce CO2 as a byproduct of answering your question. In both cases:

The useful work can be done with vastly different amounts of waste
Consumers can't see the waste happening
Market incentives alone won't fix it (bigger models are "better," just like bigger engines were "better")
Regulation and labeling changed behavior (CAFE standards, Energy Star ratings)

Here's where it gets interesting: with cars, you can't make the engine think harder about whether it needs to burn that fuel. With AI, you can. The system can reason about whether a 2,000-token response is warranted or whether 50 tokens would do. The waste is in the software, not the physics, which actually makes this a more solvable problem than automotive emissions ever were.

What Would Change

Efficiency becomes a competitive axis: Right now, benchmarks reward accuracy. An emission benchmark would reward getting the same accuracy with fewer tokens. The model that scores 95% on 200 tokens is rated higher than the one that scores 96% on 2,000 tokens.

Agent frameworks get pressure to optimize: Today's agent architectures are shockingly wasteful. Retry loops, full-context re-reads, redundant tool calls. An emissions rating would push developers toward smarter planning, better caching, and more efficient use of tools.

Users get a basis for choosing: People pick AI tools based on vibes and marketing. An emission label, like the kWh sticker on your fridge, lets them factor in efficiency. "This agent is A-rated: it completes coding tasks with 3x fewer tokens than average."

Pricing reflects reality: Token pricing today is a race to the bottom. If we internalize the environmental cost, wasteful systems become expensive, and efficient ones become cheap.

Who Builds This

No single company should own this, especially not the ones selling the tokens. It needs:

An independent body (like the EPA, or the EU's energy labeling system) that defines the benchmark tasks and scoring
Standardized test suites: 100-500 diverse tasks with known optimal token budgets across coding, writing, reasoning, and agentic workflows
Transparent reporting: providers publish emission scores alongside capability benchmarks
Tiered ratings: A through F, stars, whatever makes it readable to non-technical users

The EU is already moving in this direction with the AI Act's sustainability provisions. But "report your energy consumption" is too vague. We need a per-task efficiency metric that lets you compare systems directly.

Two Agents, One Task

Same task: "Read this 200-line file and tell me if there's a SQL injection vulnerability."

Agent A reads the file and responds in 120 tokens:

"Yes. Line 47 passes user_input directly into an f-string SQL query without parameterization. Use parameterized queries instead."

Agent B reads the file, re-reads it, then generates 1,500 tokens: a summary of what SQL injection is, a history of the OWASP Top 10, three remediation strategies with code examples, notes about ORM interactions, and a disclaimer about completeness.

Both correct. Agent B might even score higher on current benchmarks for being "thorough." But it burned 12x the tokens, and 90% of its output was unrequested padding.

Agent A passes the emission test. Agent B is a gas guzzler.

So

We don't let cars on the road without testing their emissions. We shouldn't let AI agents into production without testing theirs.

As we scale these systems to billions of users and autonomous operation, we should probably figure out if we're building the computational equivalent of a 1970s muscle car: impressive, powerful, and catastrophically wasteful.

The token is the new gallon.

I'd like to hear from anyone working on AI sustainability, green computing, or model optimization. How would you design the benchmark?

The Dream Framework: How Organized Thought Lets You Build Anything in the AI Age

Osama Alghanmi — Wed, 25 Feb 2026 20:16:58 +0000

AI doesn't fix messy thinking. It accelerates it.

Give an LLM a vague idea and you get a vague response. Give it a well-structured document with clear terminology, scoped problems, and tracked gaps — and it becomes the most productive collaborator you've ever worked with.

The bottleneck in 2026 isn't writing code. AI writes code fast. The bottleneck is knowing what to build — and being able to articulate it clearly enough that both humans and AI can execute on it.

This post introduces a framework for doing exactly that. It's not about AI tools. It's about how you organize your thoughts so that any complex problem becomes approachable.

The Framework: 7 Phases

Dream → Concrete → Divide → Gaps → Fix → Realize → Share
  ↑                                                   |
  └───────────────── feedback loop ────────────────────┘

Each phase transforms your thinking. Each one produces an artifact. Here's how they work.

Phase 1: Dream

You have an idea. It's half-formed, ambitious, probably unrealistic in its current shape. That's fine.

Prompt AI with whatever is in your head — even a single sentence — and let it generate a dream document. This is aspirational, not precise. The point is to get the idea out of your head and into a document where you can see it, react to it, and start shaping it.

Example prompt:

I want to build an AI-powered medical diagnosis platform
that helps doctors catch rare diseases earlier. A patient
describes symptoms, the system triages, suggests possible
diagnoses, and routes to the right specialist.

Generate a dream document with:
- The vision (what does this look like when it's done?)
- Current landscape (what exists today and what's missing?)
- Key concepts I'll need to define
- Open questions

What you get back:

A structured dream doc. Maybe 2-3 pages. It captures your intent, maps the landscape (UpToDate, Isabel Healthcare, Ada Health — what they do well, where they fall short), and surfaces questions you hadn't thought of yet. "What does 'catch earlier' mean? Faster triage? Better differential diagnosis? Flagging patterns across patient history?"

You didn't need to organize your thoughts first — AI did the first pass. Now you have something to react to.

The dream document is not a plan. It's a compass. It tells you the direction, not the steps.

Artifact: dreams/ai-diagnosis-platform.md

Phase 2: Concrete

Now you take the dream and turn it into a concrete reference document. This is structured, precise, and scoped. Define your terms. Draw your architecture. Specify what's in and what's out.

This is where AI earns its keep. Feed it the dream doc:

Here's my dream doc: [paste].
Turn this into a concrete reference document with:
- Defined terms and concepts
- Architecture sections with clear boundaries
- Scope (what this covers, what it doesn't)
- Open questions marked as [GAP] placeholders

Example result:

What started as "I want AI to help doctors catch rare diseases" becomes a reference document covering:

Symptom intake engine: How patients describe symptoms, structured vs. free-text, multi-language support
Diagnosis model: Differential diagnosis ranking, confidence scores, explainability requirements
Specialist routing: Matching diagnoses to specialties, urgency tiers, availability awareness
Patient records: EHR integration, data formats (FHIR/HL7), privacy boundaries
Compliance layer: HIPAA, FDA Software as Medical Device (SaMD), audit logging
Clinical UI: Doctor-facing dashboard, patient-facing intake, mobile vs. desktop
Scope boundaries: "V1 does NOT include: prescription management, insurance billing, lab ordering"

This document is now your single source of truth. Not the code. Not chat history. Not someone's memory. The document.

Artifact: docs/Diagnosis_Platform.md

Phase 3: Divide

Your concrete doc is getting long. Some sections are 10 pages on their own. That's the signal to divide.

Break the concrete document into focused division documents, each deep enough to stand alone but connected to the whole.

Here's my concrete doc: [paste].
Which sections are complex enough to deserve their own
focused document? For each, suggest a title and scope.

Example:

A medical diagnosis platform reference doc naturally divides into:

Division Doc	Covers
`Symptom_Engine.md`	Intake flow, symptom normalization, multi-language parsing
`Diagnosis_Model.md`	Differential ranking, confidence thresholds, explainability
`Specialist_Routing.md`	Specialty matching, urgency tiers, referral workflows
`Patient_Records.md`	EHR integration, FHIR/HL7 formats, data retention
`Compliance.md`	HIPAA controls, SaMD classification, audit trail
`Clinical_UI.md`	Doctor dashboard, patient intake, mobile responsiveness

These aren't just knowledge divisions — they're your code modules. Each division doc maps directly to a real unit of code: a microservice, a package in a monorepo, a module in a monolith, or a bounded context in a domain-driven design. The doc describes what the module does, the code implements it.

Division Doc          →  Code Module
─────────────────────────────────────────────
Symptom_Engine.md     →  packages/symptom-engine/
Diagnosis_Model.md    →  packages/diagnosis-model/
Specialist_Routing.md →  packages/specialist-routing/
Patient_Records.md    →  packages/patient-records/
Compliance.md         →  packages/compliance/
Clinical_UI.md        →  apps/clinical-dashboard/

Once docs map to code, you create an index document — a single file that sits at the root of your project and maps every doc to its code module. Think of it as the table of contents for your entire system. When an AI agent (or a new team member) needs to work on routing, they look at the index, find Specialist_Routing.md → packages/specialist-routing/, and have full context before touching a line of code.

## Project Index

| Working In | Primary Doc | Gaps |
|---|---|---|
| `packages/symptom-engine/` | [Symptom_Engine.md](docs/Symptom_Engine.md) | [Symptom_Engine_Gaps.md](docs/Symptom_Engine_Gaps.md) |
| `packages/diagnosis-model/` | [Diagnosis_Model.md](docs/Diagnosis_Model.md) | [Diagnosis_Model_Gaps.md](docs/Diagnosis_Model_Gaps.md) |
| `packages/specialist-routing/` | [Specialist_Routing.md](docs/Specialist_Routing.md) | [Specialist_Routing_Gaps.md](docs/Specialist_Routing_Gaps.md) |
| `packages/patient-records/` | [Patient_Records.md](docs/Patient_Records.md) | [Patient_Records_Gaps.md](docs/Patient_Records_Gaps.md) |
| `packages/compliance/` | [Compliance.md](docs/Compliance.md) | [Compliance_Gaps.md](docs/Compliance_Gaps.md) |
| `apps/clinical-dashboard/` | [Clinical_UI.md](docs/Clinical_UI.md) | [Clinical_UI_Gaps.md](docs/Clinical_UI_Gaps.md) |

This index becomes the most important file in the repo. It's the bridge between organized thought and organized code.

Artifact: docs/DX_Symptom_Engine.md, docs/DX_Compliance.md, + root CLAUDE.md index

Phase 4: Gaps

Here's where the framework really works. Once you have concrete docs and division docs, you can see what's missing.

Gaps aren't failures. They're the framework doing its job. You can't see what's missing until you've written what's there.

Track gaps with gap codes — short identifiers that make them searchable and referenceable:

### GAP-DX004: Model suggests diagnosis but doesn't explain reasoning

- **Phase**: Diagnosis output
- **Area**: Diagnosis model — result presentation layer
- **Impact**: Doctor sees "Possible: Lupus (82% confidence)"
  but no explanation of which symptoms contributed or why
  alternatives were ruled out. Doctor can't trust or verify
  the suggestion. Useless in clinical practice.
- **Root Cause**: Model outputs a ranked list with scores
  but no reasoning chain. Explainability was never specified
  in the architecture — it was assumed to be a UI concern.
- **Fix**: Add an explainability module that maps each
  diagnosis to contributing symptoms, relevant patient
  history, and ruled-out alternatives. Display as
  "evidence for / evidence against" in the clinical UI.
- **Priority**: Critical
- **Status**: Open

The gap code format gives you:

Field	Purpose
Code	Searchable ID (GAP-DX004, GAP-C001) with category prefix
Phase	When in the system this surfaces
Area	Which module or concept is affected
Impact	What users experience when this gap exists
Root Cause	Why the gap exists — not symptoms, causes
Fix	Proposed solution (can be a phased plan)
Priority	Critical / High / Medium / Low
Status	Open / In Progress / Fixed (with date)

Category prefixes keep gaps organized: GAP-DX for diagnosis, GAP-SE for symptom engine, GAP-C for compliance, GAP-UI for clinical interface. You'll develop your own categories as your project grows.

Artifact: docs/DX_Diagnosis_Gaps.md

Phase 5: Fix → Update

Fix the gaps. But not all at once.

Always ask for a phased implementation plan. Gaps have dependencies. Some are prerequisites for others. Trying to fix everything simultaneously creates chaos.

Here are my open gaps: [paste gap doc].
Here's the main concrete doc for context: [paste relevant section].
Create a phased implementation plan:
- Phase 1: Critical gaps that unblock other work
- Phase 2: High-priority gaps
- Phase 3: Medium-priority improvements
For each phase, estimate scope and list dependencies.

When a gap is fixed:

Update the gap doc — mark status as Fixed (2026-02-22), note what was done
Update the main concrete doc — the reference doc must reflect reality
Archive the old version — move superseded docs to archive/. Don't delete them. They're the history of your thinking

The concrete document evolves. Version 1 had 20 gaps. Version 2 closes 15 and discovers 5 new ones. Version 3 closes those and the doc stabilizes. This is convergence — each pass gets you closer to a complete, honest description of your system.

Artifact: Updated docs/Diagnosis_Platform.md, archived archive/gaps/DX_Diagnosis_Gaps_v1.md

Phase 6: Realize

Build real things from your docs. Projects are proof that the framework works.

Each project tests your framework against reality. When something breaks, the question is: which doc is wrong? The issue traces back to a gap in docs, not just a bug in code.

Example:

From one set of diagnosis platform docs, you build pilot deployments: one for an urgent care clinic (fast triage, high volume, common conditions), one for a rural hospital (limited specialists on-site, telemedicine routing), one for a pediatric practice (age-adjusted symptom interpretation, different reference ranges).

Each deployment tests the docs against a different reality. When the rural hospital pilot revealed that the specialist routing assumed specialists were in-house — but rural hospitals route to remote telemedicine providers with different availability windows — you didn't just patch the code. You:

Created GAP-SR002 in the routing gaps doc
Documented the root cause (routing model assumed same-building availability, not async telemedicine)
Fixed it with a phased plan (Phase 1: add remote-provider availability model, Phase 2: async consultation workflow)
Updated Specialist_Routing.md

Now the urgent care and pediatric deployments automatically handle telemedicine routing. Every project makes the docs better. Every doc improvement makes future projects more reliable.

Cross-module composition

Here's where the divide phase pays compound interest. Because each module has its own self-contained doc, you can mix and match modules across entirely different projects. Not every project needs every module. New projects are assembled by selecting which division docs to include.

Project	Modules Used
Urgent care triage kiosk	`Symptom_Engine` + `Clinical_UI`
Rural telemedicine platform	`Symptom_Engine` + `Diagnosis_Model` + `Specialist_Routing`
Clinical research tool	`Diagnosis_Model` + `Patient_Records` + `Compliance`
Patient self-check app	`Symptom_Engine` + `Clinical_UI` (patient-facing subset)
Hospital compliance auditor	`Compliance` + `Patient_Records`

The urgent care kiosk doesn't need the full diagnosis model — it just needs fast symptom intake and a clean UI to hand off to the doctor. The research tool doesn't need specialist routing — it needs deep diagnosis data with compliant record access. Each project pulls the modules it needs, and the docs tell you exactly what you're getting.

This is the same principle behind monorepo packages, microservice composition, or even Unix pipes — small, well-documented units that combine into larger systems. The difference is that here, the composition starts at the documentation level. You decide what a project needs by reading docs, not by reading code.

Artifact: projects/urgent-care-pilot/, projects/rural-hospital-pilot/, etc.

Phase 7: Share

Write about your process. Teaching forces you to understand what you actually did.

Blog posts, READMEs, tutorials, internal docs — the medium doesn't matter. What matters is that you explain your framework to someone who doesn't have your context. This surfaces assumptions you didn't know you were making.

Sharing also closes the loop. A blog post about your diagnosis explainability approach might inspire a reader to suggest symptom-graph visualization instead of flat evidence lists. That becomes a new dream. The cycle restarts.

Artifact: Blog posts, tutorials, public documentation

The Takeaway

The framework is simple:

Dream it → Write it down → Break it apart → Find what's missing → Fix it → Build it → Share it.

In the AI age, organized thought is the highest-leverage skill you can develop. Not prompt engineering. Not knowing which model to use. Clarity of thought — the ability to take a messy idea and refine it into something precise enough that both humans and AI can execute on .

A note on maintenance: docs drift. Code changes, APIs shift, dependencies update. Treat drift as another gap — audit periodically, update docs when code changes, and archive old versions instead of deleting them. The history of your thinking is as valuable as the thinking itself.

Figure It Out As You Go: Designing Software in the Age of AI

Osama Alghanmi — Sat, 21 Feb 2026 04:32:43 +0000

You don't need a perfect design upfront. You need a direction and the willingness to keep refining until things converge.

This is what I learned after building the same app a dozen times, burning it down, and rebuilding it, until the system taught me what it wanted to be.

The Myth of the Perfect Upfront Design

Every software project starts the same way: someone draws boxes on a whiteboard and declares, "This is the architecture." There's usually a lot of nodding. Sometimes there's a second whiteboard.

Then you actually start building, and reality shows up uninvited.

The boxes don't fit. The data flows the wrong way. That service you thought would be simple has seventeen edge cases. By week three, you're writing code that quietly apologizes to the whiteboard.

The hard truth is: you cannot know the full shape of your system before you've built parts of it. Requirements lie. Users surprise you. Scale reveals things that no diagram predicted.

And that's fine. The problem isn't that your design was wrong. The problem is treating the original design as sacred.

Eventual Consistency, But For Your Codebase

If you've worked with distributed systems, you know the concept of eventual consistency: different nodes in a system might have different views of the data at any given moment, but given enough time and communication, they all converge to the same state.

Your software design works the same way.

You start with incomplete information. Your architecture has gaps. Your understanding of the domain is partial. But if you keep iterating, each cycle making the design a little more honest, a little more aligned with reality, you converge toward something that actually fits.

The goal isn't to get it right immediately. The goal is to keep getting less wrong.

Call it Figure-It-Out-As-You-Go (FIAYG) Development. Not as catchy as TDD or DDD, but considerably more honest about how software actually gets built.

The key is: every time you learn something new, from a bug, from user feedback, from hitting a scaling wall, you encode that learning into the architecture. You don't just fix the symptom. You fix the system so the symptom can't recur.

How We Built Almadar (Or: A Story of Productive Chaos)

Almadar is a declarative framework that compiles state-machine schemas into full-stack apps. A single .orb file describes your entities, behaviors, and UI, and the compiler generates a working React frontend, Express backend, and database models.

That's what it is now. Here's how we got there.

Stage 1: The Single Project

It started simple. We had one project, a client that needed a CRUD-heavy business application. We hand-coded it the normal way: React components, Express routes, TypeORM entities. Boilerplate everywhere.

We noticed we were writing the same patterns over and over: a table to list records, a modal to create them, a form to edit them, and a confirmation to delete them. Copy. Paste. Rename. Repeat.

There must be a better way.

So we tried something: what if we described the data and behavior in a JSON schema, and generated the boilerplate from that?

It was rough. The schema was barely structured. The generator was a string template with fs.writeFileSync calls. But it worked. The client was happy. We shipped faster.

What we learned: The 80% of every app that is boilerplate can be described declaratively. The 20% that's unique is what you actually want to spend time on.

Stage 2: The Second Client Breaks Everything

The second client had different requirements. Our generator was too tightly coupled to the first client's patterns. We'd hardcoded assumptions everywhere: naming conventions, file structure, component hierarchy.

We could have hacked it. Instead, we stopped and asked: What would a general version of this look like?

This is where the architecture started to crystallize. We introduced the concept of Orbitals, self-contained feature modules that combine an entity (data shape), a trait (behavior as a finite-state machine), and a page (route). We separated the schema definition from the code generation.

What we learned: The moment you have a second use case, your abstractions reveal themselves. If it doesn't generalize, it wasn't an abstraction. It was a coincidence.

Stage 3: The Monorepo and the Constraints

As the project count grew, so did the chaos. Each client project had its own design system, its own component variations, its own idea of what a "button" looked like. We were maintaining ten flavors of the same component.

So we restructured everything into a monorepo with explicit rules:

Core components live in @almadar/ui, shared, versioned, never duplicated
Client design systems live in projects/{name}/design-system/, extending core, not replacing it
The compiler is in orbital-rust/, sacred, never modified without discussion
Generated code goes in projects/{name}/app/, never edited directly

More importantly, we added constraints. Hard rules the team encodes in a CLAUDE.md file that every developer (human and AI) must follow:

Never use raw HTML elements, always use design system components
Schema first, edit the .orb file, recompile, never touch generated code
Compiler is sacred, adding a rule requires explicit approval

And we enforced those constraints with a custom ESLint plugin (@almadar/eslint). Not optional guidelines — actual errors that block the pre-commit hook. Zero warnings allowed. Some of the rules we built:

Rule	What it catches
`no-raw-dom-elements`	Blocks `<div>`, `<span>`, `<button>`, etc. Use `VStack`, `Typography`, `Button` instead
`no-as-any`	Blocks `as any` type casts. Fix the actual type issue
`no-import-generated`	Blocks importing from `projects/*/app/`. Generated code is not an API
`require-closed-circuit-props`	Every component must accept `className`, `isLoading`, `error`, `entity`
`require-event-bus`	Interactions must use `useEventBus()`, not raw `onClick`
`require-display-name`	Every component must set `displayName` for debugging
`require-stories`	Every new component must ship with a `.stories.tsx` file
`event-naming-convention`	UI events must follow the `UI:EVENT_NAME` pattern
`template-no-hooks`	Template components are pure. No `useState`, no `useEffect`
`template-no-iteration`	Templates don't loop. The organism does the iteration
`organism-no-callback-props`	Organisms communicate through the event bus, not prop callbacks

The pre-commit hook runs ESLint on every staged .ts/.tsx file. If any rule fires, the commit is blocked. No exceptions. Every rule is severity 2 (error), not a warning. Warnings are aspirational. Errors are architecture.

The result: a new developer, human or AI, can't accidentally violate the design principles. The linter says no before the PR is even opened.

Constraints sound limiting. They're actually liberating. When the rules are clear, decisions get faster, inconsistencies get caught earlier, and new team members can contribute without breaking things.

What we learned: A monorepo without constraints is just a polite monolith. Constraints are the architecture, and linting is how you make them real.

Stage 4: AI Changes the Rules

Here's where it gets interesting.

When AI coding assistants arrived, our constraint-based architecture proved to be exactly what they needed to work well. An LLM with a clear schema to edit, a pattern registry to validate against, a linter that blocks bad patterns, and a compiler that says "no" to broken output? That's a productive AI agent.

An LLM working in a free-form codebase with no rules? That's a very confident agent who confidently does the wrong thing.

We formalized this: the AI gets the constraints in CLAUDE.md, checks the pattern registry before adding components, runs ESLint on every file it changes, and validates the schema with the Orbital compiler before declaring anything done. The compiler is the AI's code reviewer, and it never gets tired, never misses a case, and runs in under 50ms.

The architecture we stumbled into through iteration turned out to be the right architecture for AI-assisted development. We didn't plan that. We converged on it.

What we learned: AI amplifies whatever structure (or chaos) already exists in your codebase. Constraints aren't bureaucracy. They're the difference between an AI that helps and an AI that confidently breaks things.

The FIAYG Playbook

If you're a beginner, here's how to apply this without building a framework from scratch:

1. Start simple. Embarrassingly simple.

Your first version should do one thing. Not the thing, plus error handling, plus caching, plus a configuration system. Just the thing. You will learn more from shipping something small than from designing something large.

2. Notice repetition, it's a message

When you write the same code for the third time, that's the codebase telling you something wants to be abstracted. Don't abstract on the first repetition (premature). Don't ignore the third (negligence). The second time is the signal, the third is the confirmation.

3. Encode your learnings as constraints

When you find a bug pattern — like a modal that can get stuck open — don't just fix this one modal. Figure out what rule would prevent that class of bug entirely. Write it down. Enforce it. In Almadar's case, we turned "every modal must have a CANCEL transition" into a compiler validation rule, and "never use raw HTML elements" into a linting error. In your project, it might be a custom ESLint rule, a pre-commit hook, or a code review checklist. The medium doesn't matter. What matters is that the rule is automatic. If it requires a human to remember it, it will eventually be forgotten.

4. Your architecture should get smaller over time

Every time you spot a pattern and generalize it, you should be writing less code to accomplish the same thing. If your codebase keeps growing at the same rate forever, you're accumulating complexity, not managing it. The goal is more functionality per line, not more lines.

5. Don't fear the pivot

We renamed things. We deleted entire packages. We moved the design system twice. Every time we did, the system got cleaner, and the rules got clearer. A pivot isn't a failure. It's the evidence that your understanding has improved.

What Convergence Looks Like

After several years and many client projects, here's what we converged on:

One schema file per project, the single source of truth
One compiler, deterministic, validates 50+ rules, generates all boilerplate
One design system with per-project extensions
One custom ESLint plugin, 17 rules enforced on every commit
One standard library of reusable behaviors (CRUD, wizards, master-detail, pagination)
One constraint that every developer and AI agent follows

The Takeaway

The best software architecture isn't the one you design before you start. It's the one that emerges from listening to what your system is trying to tell you, through bugs, through repetition, through the friction you feel when something is wrong.

Figure it out as you go. Encode what you learn. Keep getting less wrong.

Consistency is eventual. Ship anyway.

JSON That Thinks: A Programming Language Inside JSON

Osama Alghanmi — Thu, 19 Feb 2026 14:22:47 +0000

What if JSON wasn't just a data format?

What if it was a programming language?

We built a Turing-complete language that is a strict subset of JSON.
No new syntax. No custom parser. Every program is valid JSON.

This is Almadar.

The Core Idea

In 1958, John McCarthy introduced S-expressions in Lisp:

(+ 1 2)
(if (> x 10) "big" "small")

S-expressions are nested lists where the first element is the operator.

JSON arrays are nested lists.

["+", 1, 2]
["if", [">", "x", 10], "big", "small"]

That's it.

S-expressions already fit perfectly inside JSON arrays.
Instead of inventing new syntax, we interpret what JSON already expresses.

What an Almadar Program Looks Like

An Almadar program is composed of Orbitals — the basic building blocks of the system.

Each Orbital encapsulates three core elements:

Entity — the data model
Trait — the behavior
Page — the UI

Entity — The Data Model

The Entity defines the structure of data.
It declares fields, types, and constraints.

It is:

The schema
The memory
The state container

It holds the data the system operates on.

Trait — The Behavior

A Trait defines behavior.

Technically, a Trait is a reusable state machine linked to an Entity.

It contains:

States
Transitions
Guards (conditions written as S-expressions)
Effects (actions like set, emit, etc.)

Traits encapsulate logic and can be reused across orbitals.
They are the computational core of the system.

Page — The UI

A Page defines the user interface.

It describes:

Layout
Components
Bindings to entity fields
Event triggers

Pages react to entity state and dispatch events that drive Traits.

Example

{
  "name": "ApprovalWorkflow",
  "orbitals": [{
    "entity": {
      "name": "Request",
      "fields": [
        { "name": "amount", "type": "number" },
        { "name": "status", "type": "enum", "values": ["pending", "approved", "rejected"] }
      ]
    },
    "traits": [{
      "name": "ApprovalTrait",
      "linkedEntity": "Request",
      "stateMachine": {
        "states": [
          { "name": "Pending", "isInitial": true },
          { "name": "Approved" },
          { "name": "Rejected" }
        ],
        "transitions": [{
          "from": "Pending",
          "to": "Approved",
          "event": "APPROVE",
          "guard": ["and",
            [">=", "@user.roleLevel", 3],
            ["<", "@entity.amount", 10000]
          ],
          "effects": [
            ["set", "@entity.status", "approved"],
            ["emit", "REQUEST_APPROVED"]
          ]
        }]
      }
    }]
  }]
}

Structure is JSON.
Logic is JSON arrays.
Execution is deterministic and recursive.

What Is a Guard?

A guard is a conditional expression that determines whether a state transition is allowed to execute.

A transition only fires if its guard evaluates to true.
If the guard evaluates to false, the transition is blocked.

Guards are pure expressions — they have no side effects.

Guard Example

{
  "from": "Pending",
  "to": "Approved",
  "event": "APPROVE",
  "guard": ["and",
    [">=", "@user.roleLevel", 3],
    ["<", "@entity.amount", 10000]
  ],
  "effects": [
    ["set", "@entity.status", "approved"]
  ]
}

This transition runs only if:

The user's role level is at least 3
The request amount is less than 10,000

If either condition fails, the transition does nothing.

Guard Evaluation

Guards are evaluated recursively:

["and",
  [">=", "@user.roleLevel", 3],
  ["<", "@entity.amount", 10000]
]

Evaluation steps:

Resolve bindings (@user.roleLevel, @entity.amount)
Evaluate inner expressions
Evaluate the outer operator

The result must be a boolean.

Guards can use:

Logical operators: and, or, not
Comparisons: =, !=, <, >, <=, >=
Arithmetic
Nested expressions
References to @entity, @user, or @payload

Conceptually, a guard is the equivalent of an if condition for a transition.

Why This Is a Programming Language

Almadar is Turing-complete because it provides:

Mutable state (entity fields)
Deterministic state machines
Conditional logic
Effects (set, emit)
Self-transitions (loops)
Event-driven communication

A self-transition with a guard and state updates is equivalent to a while loop:

{
  "from": "Computing",
  "to": "Computing",
  "event": "TICK",
  "guard": [">", "@entity.counter", 0],
  "effects": [
    ["set", "@entity.counter", ["-", "@entity.counter", 1]],
    ["emit", "TICK"]
  ]
}

State = memory.
Transitions = control flow.
Expressions = computation.

That's a complete computational model.

The Proposal

Almadar proposes a simple shift:

Keep JSON.
Interpret arrays as S-expressions.
Combine them with state machines for control flow.
Treat structured data and executable logic as one system.

No new grammar.
No new syntax rules.
Just structured computation inside the world's most universal data format.

JSON already won.

Now it can think.

[Boost]

Osama Alghanmi — Thu, 19 Feb 2026 13:54:43 +0000

AI Agents Don’t Scale Like Chatbots

ModelIndex ・ Feb 19

#ai #devops #machinelearning #rag

Finite State Machines: The Most Underused Design Pattern in Frontend Development

Osama Alghanmi — Thu, 19 Feb 2026 13:51:33 +0000

If you're using useState for complex UI, you're probably doing it wrong. There's a 50-year-old solution you're ignoring.

The Boolean Flag Trap

Here's a familiar pattern:

function UserProfile() {
  const [isLoading, setIsLoading] = useState(false);
  const [isError, setIsError] = useState(false);
  const [isEditing, setIsEditing] = useState(false);
  const [isSaving, setIsSaving] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');

  const handleSave = async () => {
    setIsSaving(true);
    setIsError(false);
    try {
      await saveUser(user);
      setIsEditing(false);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSaving(false);
    }
  };

  // What combinations are valid?
  // isLoading=true, isError=true?
  // isEditing=true, isSaving=true?
  // Who knows!
}

This creates 2^n possible states (32 combinations for 5 booleans). Most are invalid or nonsensical.

The State Machine Alternative

What if you explicitly defined valid states?

{
  "states": [
    { "name": "idle", "isInitial": true },
    { "name": "loading" },
    { "name": "editing" },
    { "name": "saving" },
    { "name": "error" }
  ],
  "events": ["FETCH", "EDIT", "SAVE", "SUCCESS", "ERROR", "CANCEL"],
  "transitions": [
    { "from": "idle", "to": "loading", "event": "FETCH" },
    { "from": "loading", "to": "idle", "event": "SUCCESS" },
    { "from": "loading", "to": "error", "event": "ERROR" },
    { "from": "idle", "to": "editing", "event": "EDIT" },
    { "from": "editing", "to": "saving", "event": "SAVE" },
    { "from": "saving", "to": "idle", "event": "SUCCESS" },
    { "from": "saving", "to": "error", "event": "ERROR" },
    { "from": "editing", "to": "idle", "event": "CANCEL" },
    { "from": "error", "to": "idle", "event": "CANCEL" }
  ]
}

Now there are exactly 5 states and 9 valid transitions. No impossible combinations.

Visualizing the Difference

Boolean Flags: Spaghetti State

         isLoading=true
        /             \
isError=true?      isEditing=true?
      /                 \
     ?                   ?

Any combination is possible. Bugs arise from invalid states you didn't consider.

State Machine: Directed Graph

                    ┌─────────┐
         ┌─────────►│  idle   │◄────────┐
         │          └────┬────┘         │
         │               │              │
    ERROR│          FETCH│         SUCCESS
         │               ▼              │
    ┌────┴───┐      ┌─────────┐        │
    │ error  │      │ loading │        │
    └───┬────┘      └────┬────┘        │
        ▲                │             │
        │           SUCCESS            │
        │                │             │
        │                ▼             │
        │           ┌─────────┐        │
        └───────────┤ editing ├────────┘
                    └────┬────┘
                         │ SAVE
                         ▼
                    ┌─────────┐
         ┌─────────│ saving  │─────────┐
         │         └─────────┘         │
    ERROR│                              │SUCCESS
         │                              │
         └──────────────────────────────┘

Every path is explicit. Invalid transitions don't exist.

Real-World Example: Form Submission

The Boolean Way

function ContactForm() {
  const [formData, setFormData] = useState({});
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [isSuccess, setIsSuccess] = useState(false);
  const [isError, setIsError] = useState(false);
  const [errorMessage, setErrorMessage] = useState('');

  const submit = async () => {
    setIsSubmitting(true);
    setIsError(false);
    setIsSuccess(false);

    try {
      await api.submit(formData);
      setIsSuccess(true);
    } catch (e) {
      setIsError(true);
      setErrorMessage(e.message);
    } finally {
      setIsSubmitting(false);
    }
  };

  // Bug: What if isSuccess and isError are both true?
  // Bug: Can I submit again while isSubmitting?
  // Bug: What clears isSuccess?
}

The State Machine Way

Define explicit states and transitions:

{
  "states": [
    { "name": "editing", "isInitial": true },
    { "name": "validating" },
    { "name": "submitting" },
    { "name": "success", "isTerminal": true },
    { "name": "error" }
  ],
  "events": ["SUBMIT", "VALIDATED", "SUCCESS", "FAILURE", "RETRY", "EDIT"],
  "transitions": [
    { "from": "editing", "to": "validating", "event": "SUBMIT" },
    {
      "from": "validating",
      "to": "submitting",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", true]
    },
    {
      "from": "validating",
      "to": "editing",
      "event": "VALIDATED",
      "guard": ["=", "@validation.valid", false]
    },
    { "from": "submitting", "to": "success", "event": "SUCCESS" },
    { "from": "submitting", "to": "error", "event": "FAILURE" },
    { "from": "error", "to": "editing", "event": "RETRY" }
  ]
}

Benefits:

✅ Can't submit while already submitting
✅ Validation happens in its own state
✅ Error and success are mutually exclusive
✅ Clear paths for retry

If you're using XState, this maps directly. If you prefer a lighter approach, even a plain TypeScript discriminated union gets you most of the way:

type FormState =
  | { status: 'editing' }
  | { status: 'validating' }
  | { status: 'submitting' }
  | { status: 'success' }
  | { status: 'error'; message: string };

Why Developers Avoid State Machines

Myth 1: "They're Too Complex"

Reality: Boolean flags seem simpler until you have 5+ of them. Then the interaction matrix becomes incomprehensible.

Myth 2: "They're Only for Games"

Reality: Game developers use FSMs because they work. UI is just like a game: user actions trigger state changes.

Myth 3: "They're Hard to Change"

Reality: Changing a state machine means adding a state or transition. Changing boolean flags means hunting through useEffect chains.

When to Use State Machines

Scenario	Boolean Flags	State Machine
2-3 simple states	✅ Okay	✅ Better
Async operations	❌ Buggy	✅ Clear
Multi-step flows	❌ Messy	✅ Perfect
Complex UI modes	❌ Impossible	✅ Ideal

Real-World Analogy: Traffic Lights

Traffic lights are the canonical state machine:

Red → Green → Yellow → Red

Imagine if traffic lights used boolean flags:

const [isRed, setIsRed] = useState(true);
const [isGreen, setIsGreen] = useState(false);
const [isYellow, setIsYellow] = useState(false);

// Bug: All could be true!
// Bug: All could be false!
// Bug: Green could turn directly to Red!

Traffic engineers use state machines because lives depend on predictable states.

Your users' sanity depends on it too.

Try It: Convert a Boolean Mess

Take this boolean-heavy component:

function Checkout() {
  const [isCartOpen, setIsCartOpen] = useState(false);
  const [isCheckingOut, setIsCheckingOut] = useState(false);
  const [isProcessing, setIsProcessing] = useState(false);
  const [isComplete, setIsComplete] = useState(false);
  const [hasError, setHasError] = useState(false);
  // ... nightmare of useEffect
}

Convert to explicit states:

states: browsing → cartOpen → checkoutForm → processing → complete
                                                        ↘ error → checkoutForm (retry)

The state machine version has 6 explicit states instead of 32 possible boolean combinations.

The Takeaway

Finite state machines aren't academic exercises — they're practical tools for managing complexity.

2-3 booleans: Probably fine
4+ booleans: Consider a state machine
Async flows: Definitely use a state machine
Multi-step UI: State machine or bust

Libraries like XState make this easy in any React/Vue/Svelte project.