To me this is optimization problem. How can we solve a problem if we don't understand it? Understanding takes a lot of effort exactly because our minds are wandering through useless context all the time, and not to mention interruption.
I formulate this problem as:
> Optimize for understanding
I know how to approach solving this exact problem. In fact, I've been doing exactly this since March 2026. We need to figure out how to isolate problems and context around them. And so my best bet right now is using graphs. Links can be easily added or removed between two nodes. And context is simply a group of links and/or linked nodes.
Now. What exactly is "understanding"?
To me, this is process when we look at some unpredictable, chaotic system and then creating structure from it. The chaotic system is an entangled, spaghetti-like graph. The ordered one is one we [hopefully] have in our brains, which allows us to act on it. I don't want to repeat entire article I wrote about this so if you want you can find it on my recent project (it's not ready for HN prime-time yet but I'll post demo soon).
But tl;dr we have "chaotic/unknown graph" and "structured/understood graph", and the bottleneck is moving nodes and links between these two.
The faster we understand the world around us, the better we understand why problems appear, and how to fix them. And once I realized this, to me it became clear where we need to move forward: to connect everything together in a way that makes understanding quick.
And fun fact, I already did this: I connected my article to yours.
That’s great! But don’t fall into the trap that the graph is the ultimate representation of all. You will get a topology, but you often need more than topologies to understand the whole. Behaviour of the parts themselves is covered in the manifesto, and there is a companion that covers the connecting of the parts: https://shapeofthesystem.com/the-shape-of-the-whole
Yeah, you need actual models to understand what is going on.
Basically, when I was using my first version of Coherence to write down what system does on lowest level I found myself imagining in my head database records. And this is exhausting when you have more than 2 tables to think about.
And so I don't want to imagine them, I want DB records represented as entities I can simply render onto screen and look at them while I think how they should interact with each other.
Now, this is topology + domain modeling. Topology/semantics here is describing what happens with those domain models over time, what states they, how they transition, what attributes models might have, and most important — which code symbol describes all of that.
So for example, I am making Job Tracking System. I need to persist Job record. I visualize it as a row in table and I can model it without attaching to code. And then we can say:
- "this entity (job) --(has_attribute)--> status", or
- "job -(described_by)-> class JobRecord",
- "job -(observed_in)-> trace",
- "job -(verified_by)-> job_test.rb".
This gives us useful semantics / description / context / domain knowledge + links it to code + test that confirms model shape, or system state transition, or process, or product behavior.
And you can describe it at any level you want.
If you don't know the implementation details yet, a greenfield project? Well, just start with Product level specs, high level description what users will see.
Is it brown-field legacy monolith 500k LoC? Well, just reverse-engineer intent from code (I even have guide how to do this and I did it on 10k LoC successfully), then align people on that "intent graph", and then connect it into CI/CD so that it becomes default review artifact on EVERY single pull request.
And the key here is to isolate context around domain model we're interested in. Make it minimal but useful to make decisions. And make it easy to pull more [relevant] context, or remove [unnecessary] context.
I still don’t fully know how to avoid tunnel vision once you have only one slice of the graph and models in front of you. E.g. failure mode might be somewhere not even described by a link or something exists entirely outside of the graph.
This would be the next thing to solve.
And meanwhile I'd like to thank you for showing me this problem.
To me this is optimization problem. How can we solve a problem if we don't understand it? Understanding takes a lot of effort exactly because our minds are wandering through useless context all the time, and not to mention interruption.
I formulate this problem as:
> Optimize for understanding
I know how to approach solving this exact problem. In fact, I've been doing exactly this since March 2026. We need to figure out how to isolate problems and context around them. And so my best bet right now is using graphs. Links can be easily added or removed between two nodes. And context is simply a group of links and/or linked nodes.
Now. What exactly is "understanding"?
To me, this is process when we look at some unpredictable, chaotic system and then creating structure from it. The chaotic system is an entangled, spaghetti-like graph. The ordered one is one we [hopefully] have in our brains, which allows us to act on it. I don't want to repeat entire article I wrote about this so if you want you can find it on my recent project (it's not ready for HN prime-time yet but I'll post demo soon).
But tl;dr we have "chaotic/unknown graph" and "structured/understood graph", and the bottleneck is moving nodes and links between these two.
The faster we understand the world around us, the better we understand why problems appear, and how to fix them. And once I realized this, to me it became clear where we need to move forward: to connect everything together in a way that makes understanding quick.
And fun fact, I already did this: I connected my article to yours.