← back to home

What If a Document Worked Like a Repo?

In my last post, I wrote about what happens to Conway’s Law when more of how a company communicates runs through AI. The short version: the floor goes up and the ceiling comes down. Every individual document gets better, and all of them together get more alike. And more and more, the conversation is two models trading documents while two humans carry them back and forth.

I ended that post on a hunch I want to dig into here. If everyone has the same tools, the document isn’t the valuable part anymore.

The artifact is the cheap part

Here’s what I mean. Any of us can generate a polished proposal, a market analysis, a project plan, in a few minutes. In whatever format we want. As long or as short as we want.

So when you send me your AI-generated doc, what are you really giving me? I could have produced something that looks a lot like it myself. What I couldn’t have produced is what you fed into it. The customer call you were on. The constraint you know about that I don’t. The two options you already ruled out and why. The thing you’re actually worried about.

That’s the part that matters now. The inputs.

Engineers already know this, even if we haven’t connected it yet. We don’t review compiled binaries. We review source code. The binary is just what you get when you run the source through the compiler, and if the binary is wrong, you don’t open it in a hex editor and start patching bytes. You fix the source and build it again.

An AI-generated document is a build artifact. The inputs are the source. And right now most of us are passing the binaries around and reviewing those.

A copy of a copy

It gets worse when the document goes through a few hands.

You write some notes and have Claude turn them into a doc. I get the doc and have my tool summarize it. I write a response based on the summary and have my tool polish it. Someone else gets my response, pastes it into theirs, and asks for the key takeaways for their team.

Every step rebuilds the whole thing from scratch. Not an edit. A reconstitution. And every rebuild loses a little. Your “I think it’s maybe around 15%, but I’m not confident” becomes “approximately 15%” becomes “15%.” A caveat drops off. A “for this one customer” turns into “customers.” Nobody did anything wrong. Each step was reasonable. But by the end, you can’t tell what anyone originally said, what was a guess, and what a model filled in to make the paragraph flow.

It’s a photocopy of a photocopy. Except each copy looks sharper than the last, so you don’t notice the detail is gone.

Everyone has their own context

This is the part I think sits underneath all of it.

When you work with one of these tools, everything it knows about your problem lives in its context. That’s the conversation so far, the files you gave it, the notes you pasted in, whatever it’s been told about who you are and what you’re doing. It’s the model’s working memory for that session. And it’s yours. Nobody else can see it.

So today, everyone is building their own private context. I pump my notes and my docs and my opinions into my session. You pump yours into yours. The only thing that crosses between us is the output. The doc.

Think about what that does to a revision. You send me a doc your session produced. I drop it into my session, which has a completely different set of inputs behind it, and I make edits. My edits make sense given everything my session knows. But my session doesn’t know what yours knew. So the doc drifts. It moves toward my context and away from yours. You get it back, and now it doesn’t quite say what you meant, so you pull it back toward yours. I pull it back toward mine.

It’s a tug of war, and neither of us can see the rope. We’re both burning tokens and time dragging the output closer to what the other person wants, when what the other person wants is sitting right there in a context we don’t have access to. The real problem isn’t the doc. It’s three steps back, in inputs neither of us can see.

And this is the Conway’s Law point in its purest form. Our communication structure is now a bunch of private contexts, connected only by the artifacts we toss between them. Of course what we build looks like that. Fragmented, a little inconsistent, reconciled after the fact by whoever touched it last.

If there’s one thing in this post I most want to solve, it’s this one.

What we could do right now

I don’t think the answer is another pitch pause. That worked because in February nobody knew what the tools could do, and two weeks of hands-on time fixed it. Everyone knows now. The gap isn’t fluency anymore. It’s that we never built a habit of sharing what goes into the tools, only what comes out.

I haven’t solved this. But when I think about what we could try tomorrow, without waiting for anyone to build anything, a few things come to mind. None of them need new software. They mostly need us to be a little less precious about polish.

The first is to sometimes send what you gave the tool instead of the doc. Your notes. The transcript. The question you’re trying to answer, what you already know, and what you’re unsure about. It would feel rough compared to a polished document, and that’s kind of the point. The person on the other end could run it through their own tool, in the format they want, asking the questions they care about. It would also fix the problem I started the last post with. The doc I got was shaped for a generic reader. If you send me your inputs, I can shape it for me.

When the finished version does go out, the inputs could go with it. A folder link, an appendix, a few lines at the bottom that say “here’s what this came from.” The few lines at the top in your own words, the ones I talked about last time, count too. They might be the most important input of all, since nobody else could have written them.

Going the other direction, imagine asking the sender a question before you drop their doc into your own session: what did you give it? What were you trying to get? It sounds like an odd question the first time. It isn’t. It’s the same thing as asking a teammate what they were going for before you rewrite their function.

And for anything that’s going to go through more than one round, picture a single shared page for the thing itself. Not the doc. The stuff behind the doc. What we’re trying to decide, what’s already settled, what’s still open, what the customer actually said. Everyone pastes it into their session before they touch a draft, and when something changes, it changes there first. It would be clunky. A Google Doc doing a job it wasn’t designed for. But of everything on this list, I suspect it’s the one most likely to slow down the tug of war, because for once our sessions would be starting from the same place.

The meetings would change too. A meeting where we argue about the wording of a generated doc is a waste. A meeting where we argue about what goes into it is where the real work is. What are we actually trying to decide? What do we know for sure? What did the customer actually say, in their words? That’s the stuff that needs two people in a room. If two agents converged on something, that’s a proposal, not a decision.

None of this is a system. It’s a handful of habits and a shared page. Which is why I keep thinking there’s a better shape for it.

What if a document worked like a repo?

The tools we have are built around the output. You type something in, you get something back, and the something you get back is what gets saved, shared, and forwarded. The inputs are scattered across a chat history nobody else can see.

Software engineering already ran into a version of this problem, and I think it stumbled into a pretty good answer.

When I work on a codebase with Claude Code, the code isn’t the only thing in the repo. There’s a CLAUDE.md file that explains the project. What it’s for, how it’s structured, the decisions we’ve already made, the things not to do. Every session reads it before it touches anything. It doesn’t matter whether it’s my session or a teammate’s, today or three months from now. Everyone starts from the same context. The file outlives any single conversation with the model, and it gets better over time as we learn what the model needs to know.

That’s shared context. It already exists. It’s just a text file in a folder.

And the repo around it does a lot of the rest. There’s a history, so you can see what changed and why. Commit messages capture the reasoning, not just the result. If two people disagree about the approach, they each make a branch, and the disagreement is right there, visible, side by side, until someone makes a call in a review. Nobody quietly overwrites anybody else’s intent. When the output is wrong, you don’t patch the build. You fix the source and build again.

Documents have none of that. A doc today is a single file, usually a generated one, floating around without its source, its history, or any record of why it says what it says.

So here’s the hypothetical I keep coming back to. What if we treated a document the way we treat a codebase?

The doc would come with its own version of a CLAUDE.md. What this document is for, who it’s for, what’s already been decided, what’s still open. The notes and transcripts and customer quotes that went into it would live alongside it, as the source, not buried in someone’s chat history. When you pick it up to revise it, your session reads all of that first. Your edits would start from what I knew, not just from what I wrote.

Revisions would have history. Not just “version 3,” but why it changed. If you think a section is wrong, you’d branch it, and your version and mine would sit next to each other, visible to both of us and to both of our tools, until we actually talked about it. That’s the kind of disagreement I want more of. Not the invisible tug of war, but divergence you can see and argue about.

And review would be about the inputs. Not “I don’t love the wording in paragraph four,” which any model can fix in a second. More like “this is missing what the customer actually said,” or “we already ruled this option out in March.” Fix the source, and everyone’s next version gets better, instead of each person patching their own copy.

There are a couple of other things I’d want in a world like that. Tools that ask before they generate. Most of the token spend I see isn’t the first draft. It’s the fifth and sixth pass trying to get the output to match something that was never clearly stated. A tool that pushed back with “what is this actually for, who’s reading it, what do you already know” would save more tokens than any model upgrade. And some way to see which parts of a document a human actually touched. Not to shame anyone. Just so the reader knows where the thinking is.

I don’t know if this is the right shape, or if a repo for every document would just be too much ceremony for most work. Probably some version of it is. But I know that the current setup, where everyone generates polished outputs in private and passes them around and regenerates them on the other end, is not the end state. It’s what happens when the tools are new and we haven’t figured out what to share yet.

You can’t share a world you’re not in

In April I wrote that if you want to change what your organization builds, change how it communicates. Back then, that meant getting everyone to the same understanding of what the tools could do. Now I think it means something more specific. Change what we pass to each other.

Right now we pass around the build artifacts and keep the source to ourselves, each of us in our own private session. Then we’re surprised when the documents drift, the revisions fight each other, and everything starts to sound the same.

The tools raise the floor. That’s worth a lot. But the ceiling has always come from people, from the weird idea and the hard conversation and the thing someone noticed that nobody else did. In a world where anyone can generate the output, that stuff lives in the inputs. That’s what we should be sharing, arguing about, and protecting.