The documentation backfill run

AI-assisted coding has a side effect most teams undercount.

When the speed of shipping increases, documentation does not keep up. Not because engineers are lazy — because the old forcing function was the friction of writing code by hand. When a feature took three days to build, documenting it was proportional. When it takes three hours, the ratio breaks.

The result is a documentation backlog that grows quietly in the background. Specs that were never written. Modules that only the original author understands. Architecture decisions that lived in a Slack thread and nowhere else.

This is not a culture problem. It is a sequencing problem.

The backfill workflow

Over a few evenings I ran a documentation backfill on a codebase using Claude’s dynamic workflow feature. The job was simple to describe:

• Go through the relevant modules
• Read the code as it actually exists
• Write a spec for each one
• Verify the spec back against the implementation

That last step matters. The point is not to generate documentation that describes what the code was supposed to do. It is to document what the code actually does, then flag where that diverges from intent. Those divergences are useful. They surface either drift that has accumulated since the original design, or intent that was never captured clearly in the first place.

The workflow ran without intervention. I was at the gym.

What to hand to the workflow

The input quality matters more than the workflow complexity.

Before running, I pointed it at specific modules rather than the whole codebase. A broad sweep produces broad output. Narrowing the scope to one area at a time produces docs that are actually useful because they reflect a bounded context someone will want to read.

The brief also included a format constraint: write specs in plain language, structured enough to be a reference, short enough to be read. Not an essay, not a one-liner. Something a new contributor could open and understand the module’s job in two minutes.

The token budget angle

There is a practical dimension here worth naming. Running a large workflow across a codebase consumes compute. Evenings and weekends are when that cost makes the most sense — it is not displacing active development work, and a slow run is fine because there is no urgency.

Pending token budgets and off-hours runs have a natural fit with backlog work like this. Documentation, test coverage, dead code analysis. Tasks that are real work but not urgent enough to block the day.

What comes out

The output is a set of spec files, one per module. Some are clean. Some flag places where the code has clearly outgrown its original intent. A few surface assumptions that were never written down.

That last category is the most valuable. An assumption that lives only in someone’s head is a risk. One that lives in a spec is a decision. The workflow surfaces them cheaply enough that it is worth running regularly, not just once.

The docs are a starting point, not a final draft. A quick human pass catches anything that sounds plausible but is slightly off. But the starting point is 80 per cent of the work, and that 80 per cent used to not get done at all.

The part the workflow cannot do

Generating the docs is the easy half.

The harder half is reading through them with a focused, clear mind. Finding where the gaps are. Noticing what is described correctly but misses the point. Closing what needs closing.

That requires a different kind of time. Not the kind you squeeze in between meetings or run in the background while you are at the gym. The kind where you sit down with the output, read slowly, and bring judgment to what you are looking at.

I am still working through that pass. It is slower than generating the docs. It is also the part that cannot be handed off. The workflow surfaces the material. The review is where the actual decisions happen — what to keep, what to rewrite, what the gaps reveal about the design itself.

This is not a failure of the workflow. It is the correct division of labour. The workflow does the retrieval and synthesis. The human does the evaluation. What changes is that the human is evaluating something concrete rather than starting from nothing. That is a meaningful shift, but it does not eliminate the need for the focused time to do the review well.

If anything, the workflow makes the review more important. When there was no documentation, there was nothing to review. Now there is. The standard goes up.