The Empathy Compiler · Mubeen Sahar

The Idea

Code is written for machines.
This rewrites it for humans.

Every system has a story. A user signs up. Their data travels through a validation layer, gets transformed, stored in a database, triggers a notification service, eventually ends up on a dashboard someone reads weeks later. This story exists in the code — but only a machine can read it as written.

The Empathy Compiler reads the code and produces the story. Not documentation. Not a diagram. A first-person narrative told from the perspective of the data itself — where it goes, what changes it, what decisions are made on its behalf, and what happens to it in the end.

The code
def process_payment(user_id, amount):
  user = User.get(user_id)
  if not user.is_verified:
    raise UnverifiedError()
  wallet = Wallet.get(user_id)
  if wallet.balance < amount:
    raise InsufficientFunds()
  wallet.debit(amount)
  Ledger.record(user_id, amount)
  notify(user, "payment_success")
  return "ok"

The story

I begin as a payment request — a number, an intention. The first thing that happens to me is a question: is this person real? If they aren't verified, I go no further. I simply end, unprocessed.

If I pass, I travel to the wallet. Another question: is there enough? If not, I end again — quietly, as a polite error.

If the wallet holds enough, something is taken from it. I watch myself become a permanent record in a ledger. Then a message goes out. Someone is notified that I exist, that I succeeded. I end as a simple "ok" — but somewhere, a notification has made a person feel reassured.

Why it matters

The gap between engineer and everyone else

Non-technical stakeholders, new team members, product managers, compliance teams — they all need to understand systems but can't read code. Current tools offer diagrams. Diagrams are abstract. A narrative is human. The Empathy Compiler bridges the gap by producing something anyone can read.

The deeper use

Engineers see their own systems differently.

When you write code, you think in terms of functions and data structures. When you read the narrative, you think about consequences — what happens to the user, where they might get stuck, what silent failure looks like from the outside. It reveals design problems that code review misses.

Features

What The Empathy Compiler produces

📖

First-person Narratives

Every function's logic is retold as a story from the perspective of the data moving through it. The narrative follows the actual execution path.

🗺️

System Story Maps

End-to-end user journeys composed from individual function narratives — "what happens when a user signs up" told as a continuous human story.

⚠️

Failure Story Mode

Generates the error path narrative — what the data experiences when things go wrong. Reveals silent failures and missing error handling intuitively.

👥

Non-technical Export

Exports as clean readable documents — PDF, Notion, Markdown — for sharing with stakeholders who will never look at a code file.

🔄

Live Regeneration

Regenerates narratives when code changes. The story stays current as the system evolves — no manual documentation effort.

🎨

Tone Modes

Technical narrative for engineers. Plain English mode for product managers. Formal mode for compliance. Same code — three different stories.

Stack

How it's built

🌳

Tree-sitter

AST Parsing

🤖

LLM API

Narrative Gen

🐍

Python

Core Pipeline

📐

NetworkX

Call Graph

⚡

FastAPI

Processing API

⚛️

React

Reader UI

📄

PDF / MD

Export

🔌

VS Code

Extension

Currently in development

AST traversal logic built · Narrative prompt engineering in progress · Testing on Python and JavaScript codebases

The EmpathyCompiler