Our documentation updates itself, because updating it is the AI's job

Every team doc I've ever seen dies the same death. Someone writes it in a burst of good intentions, it's accurate for about three weeks, and then reality moves and the doc doesn't. Six months later nobody trusts it, so nobody reads it, so nobody updates it, and now it's just a confidently wrong artifact taking up space.

The reason is boring and universal. Keeping docs current is nobody's actual job. It's the thing you do after the real work, which means it's the thing you never do.

I didn't invent the fix, I copied it

What I'm describing here is the LLM wiki pattern, and it's been going around for a while now. The idea is small: a folder of plain markdown files that an AI maintains as a side effect of working with you, rather than a document a human maintains as a chore.

Its whole argument is a swap. The reason wikis rot is maintenance burden, and the one participant in your team who does not get bored, does not forget to update the cross-reference, and does not find it beneath them to rename a page, is the model. Chat history evaporates when the session ends. A folder of markdown doesn't, and it opens in Obsidian, in VS Code, in a diff, on your phone.

I'd been running one for myself for a while before any of this. Mine is called Alt-Brain, and it's where I dump things I've read: articles, papers, notes, half-formed things about payments and design and whatever I've fallen down a hole about that month. I drop a file in and ask it to ingest. It writes a page for the source, links it to the ideas and people and products it touches, and files anything I asked it that produced a real answer.

The reason I care about that one, personally, is that it makes my reading compound instead of evaporate. I read a lot and retain embarrassingly little. Alt-Brain means the version of me from four months ago can answer a question for the version of me today, in my own words, with the sources attached. It's the single most useful piece of software in my life and it is, structurally, a folder.

So when I started building the design workflow, I pointed the same pattern at it.

What it holds, and what it deliberately doesn't

Not user docs. Not a copy of the workflow, which already exists as the workflow. This wiki holds the thinking. Why we chose this over that. What we tried that didn't work. The decisions, with their reasons attached.

The layout is the pattern's, lightly adapted:

• A schema file the AI reads at the start of every session, which is what stops each session inventing its own conventions.
• A raw drop zone for source documents, which are never modified. Immutability matters here. The source is evidence.
• Sources, one page per ingested document or conversation.
• Concepts, the standing ideas, written in the present tense.
• Decisions, dated, each one carrying what was decided, what else was considered, and why the alternatives lost.
• Analyses, which is where a question that produced a real answer gets filed so nobody researches it twice.
• An index, and an append-only log, newest first.

So I made it the AI's job

Instead of writing it myself and watching it rot, I made keeping it current a step in the work. After any significant effort, a decision made, a thing built, a problem solved, the AI updates the wiki as part of finishing. New page if the topic is new, edit the existing page if it isn't, a dated line in the running log, and a flag on anything that now contradicts something older.

The trick that makes it not rot is that the update isn't a separate task you remember to do. It's the last move of the task you were already doing.

Three conventions do most of the work, and they're cheap to steal.

Status is present tense, history goes in the log. A concept page says what is true now. It does not narrate how it got there. That's what the log is for, and keeping them separate is why the pages stay readable after a year.

Nothing gets deleted, it gets struck through and resolved. When a conclusion turns out to be wrong, the old text stays with a line through it and the correction sits underneath. Six months on, the most valuable thing on a page is often the claim that turned out to be false, because it stops you cheerfully re-deriving it.

Three inline markers, used constantly. Open question for something genuinely unresolved. Revisit for a decision that may not survive contact with next quarter. And Contradiction for the case where new evidence disagrees with an existing page, which gets flagged rather than quietly overwritten, so the disagreement is visible until somebody settles it.

There's also a periodic lint. Contradictions, orphan pages, stale claims, missing cross-references, open questions that have been open too long. It's a checklist, run occasionally, and it's the closest thing this has to gardening.

What it's actually good for

The obvious payoff is that the docs stay true. The one I didn't expect is what it does to memory across sessions. When I come back weeks later and ask "wait, why did we do it this way," the answer is written down, with the alternatives we rejected and why. I'm not reconstructing my own reasoning from scratch, which is the tax I complained about in an earlier post, just aimed at myself.

The second payoff is that it makes disagreeing with my past self cheap. Every decision page carries its rejected options, so revisiting one is a real conversation instead of an argument between two people who both half-remember.

And it does something I didn't plan for at all, which is onboard people. A designer joining the team doesn't need me to explain why the workflow has a gate after every step. There's a page. It's dated, it says what we tried instead, and it's more honest than the version I'd give them out loud, because the page was written before we knew it had worked.

The part that still needs a human

Two things, in the interest of not overselling my own system.

The rules I listed exist because an AI that likes writing will happily turn your wiki into a swamp. Update before you create. One page per topic. Without those it grows into something as useless as the stale doc, just longer. Log entries get archived by month, or the log becomes the swamp instead.

And the index, the catalog of every page, is still maintained by hand. It drifts. The instruction in the wiki's own schema is to enumerate the folder rather than trust the index when auditing, which is a polite way of saying the one file I didn't automate is the one file you can't rely on. There's a lesson in that I'm choosing not to draw too hard.

Docs don't die because writing them is hard. They die because updating them is homework nobody's assigned. Assign it. Make "update the record" the final step of the thing that changed the record, and hand that step to the one participant that never gets bored of doing it.

---

Part of a series on building an AI collaborator for our design team at Xflow. Each post stands on its own.