Ask "how does invoicing work?" in any team and watch where the question goes. Not to the docs. To a person. Usually the same person, every time.
Documentation projects fail for a boring, predictable reason: docs are hard to write and harder to maintain. So they rot. The knowledge doesn't disappear, though. It moves somewhere worse: into the heads of three or four developers. Then one of them leaves, and the answer becomes "Person X used to know."
I've been running an experiment to fix that. Not by writing better docs. By not writing them at all.
A second brain, but for a codebase
Nine months ago I started turning loose ideas into small, linked notes. The notes were useful. The links between them were better. That's where the insights came from that I'd never have found on my own.
So what if product documentation worked the same way? Not pages on Confluence. Small nodes, extracted from the codebase by skills, linked into a graph, kept in sync with pull requests and releases. Nobody writes it. A system captures it.
One twist matters more than the rest. The code is the source of truth, but the output describes the product, not the code. You don't get an explanation of the event bus. You get how invoicing works. That's a layer product people can query too, without opening a repo or pinging the tech lead.
Small, typed, linked
Every node is one small Markdown file of exactly one type: business rule, domain term, flow, constraint, assumption, unknown, defect. Types never blend. Nodes link to each other, and the links carry as much information as the nodes. When doesn't a rule apply? Where is an assumption hiding?
A meta folder defines every type: what it contains, how to extract it, how it links, with a template and a worked example. The skills are thin pointers into that folder. Want to know what a scan does? Read it.
One prompt doesn't scan a codebase
My first attempt: here's the codebase, scan it, make the team smarter. It missed about 80%. It skimmed, and where it skimmed, it guessed.
What works is going granular. A survey shows where the action is. A capability table lists the big things the product does, like generating invoices. Each capability has flows: the PDF, the API endpoint, the CLI command. Each flow has an actor who starts it and a surface where it happens.
The flow is where the magic happens. Scan one, and it fans out into every rule, constraint and term it touches, all linked.
There's a second route too: find the bounded contexts, find the doors into each domain, fan out from there. Same results, different mental model. Neither needs a tidy codebase. Even on a big ball of mud, the scans make decent educated guesses about where the boundaries are.
Nobody reads the notes
That's not a bug. The notes are raw material. The value is in what you build on top.
A QA skill turns flows, rules and existing test coverage into Gherkin scenarios, which turn into Playwright tests. A drift skill checks a flow used in five places: same steps everywhere, or is one of them missing a rule?
My favourite is the refinement report. Refinement usually means asking the tech lead and hoping he knows. Instead, the team writes a briefing upfront, the system works out which flows to scan, and it writes a report answering the questions. Every claim links back to its source notes. It can even surface bugs before anyone starts building.
Never guess
The question I get every time: is it accurate? Fair. AI gets one mistake. After that, nobody trusts it again.
So every scan runs blind, in its own folder with its own agent, and only reconciles with the existing notes afterwards. When a scan misses something, it writes down a learning, and the next scan reads it first. Every claim links to the exact file, line or test it came from.
And unknowns stay unknowns. Nodes carry open questions. A verify skill takes a deeper pass. A triage skill routes what's left to people, and once three independent answers agree, the node updates itself.
A blank and a question beat a confident guess.
Still open
Plenty. When do you scan, and how much? A thorough flow scan takes 15 to 20 minutes. Disappearing for two months to hand over a finished knowledge base is the worst thing you could do, so I scan what teams will touch next. Per PR, nightly, which branch: still figuring it out.
The code tells you how, never why. Pull requests, tickets, ADRs and Slack could add the why. And it's all in Git, so you could ask what the product looked like at any release.
Then there's the question I keep coming back to. If the notes are this atomic, could you flip the direction? Write the note, generate the code? I don't know. I really want to find out.
The moat isn't the model
Ask product and engineering how a feature works and you'll often hear two different stories. Models will keep changing. A living map of what your product actually does today is the part that's yours.
