There’s a discipline I’ve practised for a long time that I don’t hear talked about enough: writing down how I think, not what I know.
I am talking about the actual structure of how I approach a problem — what I look for first, what questions I ask before anyone else has thought to ask them, what lenses I apply and in what order, what the shape of a good answer looks like before I know what the answer is.
It requires you to catch yourself thinking and then describe the thinking, sort of metacognition, or epistemology if you want academical term.
Most people, when asked to write down what they know about architecture, produce a list of facts, patterns, principles. That’s knowledge. What I was trying to write down was something else: the engine that produces those facts, patterns, and principles in context, on demand, in response to problems I haven’t seen yet.
The discipline of making your thinking explicit — of writing it down carefully enough that someone else could follow it — is the discipline of sharpening the thinking itself. You don’t know what you actually think until you’ve tried to write it. And once you’ve written it, you start to see the gaps, the inconsistencies, the places where your intuition outran your ability to explain it.
I’ve been doing this for years. Rather then accumulating a memory of events and decisions, I tend ot accumulate structues, mental models — a description of how an experienced architect actually sees: domains, trade-offs, stakeholder dynamics, risk surfaces, the gap between what a system does and what it should do, the difference between what’s technically possible and what’s strategically right.
The Mental model
Structured knowledge is important. This should be obvious, but it isn’t always acted on. We very often settle for having knowledge - “documentation exists, and stuff from the checklist is there” at the smaller scale and documentation attached to every service you own at a larger scale.
But structured knowledge, no matter how well organized, has a gap. The gap between the knowledge existing and applying it.
A structured mental model — one you’ve articulated carefully, refined against real problems, and organized into something navigatable — is increasing usefulless of your knowledge significantly (would say order of magnitude, but it is not liek there is actual way to measure :)).
You carry the model. You apply it to each new problem yourself. The model doesn’t meet the problem — you do, using the model. For a broader usage it becomes a bottleneck when you want someone else to benefit from it: a junior architect, a team you’re advising, a domain you’re not embedded in. You can share the documentation. You can’t share the mental model. Not in very efficient way at least… Write a blogpost? Write a book? Give a talk?
The gap is the intuition. The part of the mental model that operates faster than explanation, that pattern-matches before you’ve consciously engaged, that asks the right question before the meeting has landed on what question to ask.
You can describe intuition. Describing it doesn’t transfer it.
Every format we've had for knowledge transfer — books, talks, blog posts, courses, documentation — runs into this wall. They can describe the model. They cannot enact it. The reader receives the description and then does the work of turning it into practice, alone, without scaffolding, against a learning curve that most people don't have time or support to climb.
That gap has been there for as long as people have been trying to transfer expertise. For most of history, it was simply the cost of learning — you apprenticed, you paired with someone more experienced, you made mistakes with them watching. The model transferred slowly, through exposure, through correction.
There was no other way.
Enter The “AI”
What “AI” changes is not that it makes you smarter, or faster, or able to do things you couldn’t do before. What it changes — the thing that matters most — is this:
For the first time, a written mental model can be made executable. - To a level at least.
This is, of course, LLMs, the “AI” (with large quotation marks), the Large Language Models are aweome at pattern matching and dealing with written prose - this is no brainer. Teach LLM to structure it’s pattern matching areasoning in certain way and you can have it demonstrate the analysis approach and understanding principles you are applying to the very usable level.Especially if you are not doing “rocket science”, which minimum of 99% of us dont.
You write down how you think. You structure it carefully — the lenses, the analysis frameworks, the sequence of questions, the principles that govern trade-offs. You make it explicit enough that it can be read and internalized. And then an “AI” agent internalizes it and applies it — to your codebase, your system, your problem, in your context — in real time.
Important - for my fellow SciFi freaks out there, this is why I mentioned specific cases (this time code, architecture etc) - no, you cant really generally teach it how to think like you, but for some niche things and one abstract layer you carefully choose…
The model doesn’t sit on the shelf. It works. It meets the problem you bring it. It asks the questions you would ask. It surfaces the considerations your experience would surface (under your control). Not because the “AI” is replacing your judgment — but because the written model is now an active participant in the thinking, not a static reference you consult.
I am describing potential way to try and cover the gap between structured knowledge and applied expertise — the gap that every knowledge transfer format has always had to leave open may be narrowed using Large Language Models and well crafted harnesses (from industries mega products like Codex, Claude Code to your local machine friendly qwens and gemmas and harness you wrote in python)
This is what I have tried to build one winter week in 2025.
I finally found use for the things I tried to wrte before — an architecture book I never finished, a solution architect’s guide that stalled, the article about analysis patterns — weren’t wasted. Turns out they were drafts of the mental model itself.
These were attempts to make the thinking explicit before the capability to make it executable existed. The blueprint concept, the two scales, the cognitive load argument, the themes that kept recurring in everything I wrote — they’re all now in quantum-toolbox.
quantum-toolbox
quantum-toolbox is a markdown-based executable mental model — no runtime dependencies, no plugins, no API calls — that ships as a git submodule into any project. “AI” “agents” read it at session start and gain the ability to try and do some architecture work.
The core is what I call the mental model as engine. Rather than building dozens of separate skills that each explain architecture from scratch, there’s one foundational layer that encodes the mental model itself — domains, stakeholder analysis, gap analysis, principles, the way an experienced architect actually structures a problem. Every skill inherits from this. The mental model is the engine - the archtecture thinking core; the skills are the gears.
It covers the full range:
- Analysis — codebase, architecture, security (OWASP, NIST, NIS2, ISO 27001), nonfunctional requirements, fitness functions
- Architecture — the complete TOGAF ADM cycle, C4 modeling
- Development — software design, tech stack decisions, code conventions
- Output — architecture docs, product specs, ArchiMate, presentations, compliance reports
27 skills across 4 categories. Pure markdown. Works with any “AI” agent that reads text.
The research tool, the analysis tool, the creation tool - well, mostly analysis tool, but there is potential (I do use it like this). They’re the same mental model operating at different phases of the work. You research with it, you analyse with it, you create with it. The consistency comes from the engine underneath.
What’s Next
This article is the “why” — the argument for why executable mental models matter and what they change. The interesting stuff is in the how.
Coming up in this series:
- How the mental model engine actually works — the architecture-thinking layer that makes everything else possible
- Practical TOGAF through “AI” — what happens when you give an agent the full ADM cycle
- Security analysis as a thinking framework — not a checklist, a lens
- How to customize the mental model for your organization
- The determinism of the result and token economics of teaching an “AI” HOW to “think”
Write things down. Structure the thinking, not just the conclusions. Make it explicit enough that it could be followed.
That’s been the practice. quantum-toolbox is where it landed.