Rewriting \"Let's Organize the Current State Because We Want to Automate\" Into \"Let's Just Look at the Current State as It Is\"

I was writing a document to analyze 200+ release procedure documents at our organization and visualize the deployment patterns.

I started with the stance "let's organize the current state because we want to automate." But mid-write, friction emerged, and I ended up deleting the entire automation context from the main document. I rebuilt it into a document that purely says "this is what the current state looks like."

It's a technical work log, but please read it as a record of pivoting the stance of documentation design in the middle of writing.

Background: procedures piling up

In the development organization I belong to, each release spawns one procedure document. It's created from a template, the actual work is filled in, and then it's executed.

These accumulate at about 40–45 per half-year. Each one packs a fair amount of thought and judgment — but as the count grows, it gets harder to see, at the organizational level, "what kinds of releases we do and at what frequency" and "what's routine vs. what's exceptional."

Recently, "let's organize this area and automate what we can" surfaced as an organizational topic. As the first step in that discussion, I took on the task of reading every procedure document and visualizing the deployment patterns.

This article is the record of a stance pivot that happened in the middle of that work.

Premises

First stumble: a Windows-incompatible filename

Not the main thread, but a small stumble in the first step worth recording.

When I tried to clone the repository, one file failed to check out. The cause was a > character in the filename. Windows NTFS treats it as a reserved character, so it can't be expanded locally.

In the end, I used sparse-checkout to exclude just that one file and retrieved the rest:

git sparse-checkout init --no-cone
git sparse-checkout set '/*' '!<pattern for the file>'

A detail that hits me fresh every time. Time leaking into work tangential to the main goal — that's where it starts.

Analysis approach: where to lean on AI, where humans verify

Reading and classifying 200+ documents is a multi-day job for a human. This time I decided to have Claude Code do the analysis.

The flow looked like this:

I started by reading a handful of samples to grasp the structural variation. Template-derived variation had diversified more than expected, so passing through this step before throwing the whole set at the model was the right call, I think.

From there: have the agent classify all documents in the period. For each emerging classification, pull a representative document I think fits it and check whether the document actually matches. If it's off, ask for re-classification. Iterate.

What I felt here was that the boundary between "AI's part" and "human's part" was sharper than I'd expected:

If you can hold that balance, large-document-set analysis like this is starting to become a realistic option.

The extracted patterns

In the end, things settled at 9 categories × 20 patterns. The overall structure was roughly this (simplified):

The two most frequent patterns:

These two accounted for 3–4 tenths of the total. Most of a half-year's worth of releases isn't exotic — it's "the usual single-component release."

Another important finding was that there's a cross-cutting "common post-processing" pattern executed in nearly every release. Tag attachment, deploy-table update, release-notes addendum, announcements to stakeholders. This sequence runs across virtually every release, regardless of type.

Up to this point, the work was proceeding as expected — pure analysis.

What triggered the pivot: friction emerged mid-write

Originally, I had a section called "Automation Priority Matrix" inside the main document. For each pattern, I laid out columns like:

By combining "what percentage of the whole this is," "is it easy to automate," "how high is the rollback risk," I was stepping all the way into proposals like "start automation from here."

After writing this far, friction surfaced:

Wait — is this document mixing purposes?

Is this a document that conveys "the current state is like this"? Or a document that proposes "therefore, do this"? Cramming both into the same doc made it half-baked for either purpose. As a current-state document, the strategy-proposal noise contaminates it; as a strategy proposal, the analytical descriptions are too thick.

I hesitated, but in the end I narrowed the main doc to just "this is the current state." The automation-fit, priority, and start-phase discussions — I deleted them outright. I scrubbed the automation context out of the main and rebuilt it into an "observation-only" document.

While doing it, I did have a "wait, I'm deleting this after writing all that?" moment. But it was clear at the friction level that "deleting makes it cleaner," so I committed.

Why did I want to split them apart?

From here it gets more reflective. Why did I want to separate "current-state observation" from "strategy proposal" into different documents? Sorting it out as I wrote, here are four reasons.

Reason 1: The "lifespans" of the documents differ

A current-state observation is a record of facts. As long as no new releases are added, what was correct when written stays correct.

A strategy proposal, on the other hand, ages as premises change. Organizational priorities, technology choices, headcount, business situation — small shifts in any of these make conclusions like "therefore start in this order" wobble immediately.

Mixed in one document, the proposal portion drags down the whole. Short-lifespan information ends up pulling down long-lifespan information.

Split apart, the current-state document becomes a long-lived asset, and the strategy doc can explicitly mark itself as "a proposal against today's situation."

Reason 2: The reader's mode of cognition differs

"The current state is X" is material the reader uses to make their own judgment. The reader receives facts and considers how to use them in their context.

"Therefore, let's do Y" is the writer handing the reader their judgment. The reader weighs whether to adopt, modify, or reject that judgment.

When both are mixed in one document, readers tend to read past the boundary between "fact" and "claim." There's a real risk that the writer's opinion gets received with a face that looks like fact. As the writer, I want to avoid that responsibility.

Reason 3: The discussion subjects differ

Discussion about a current-state observation centers on "are the facts accurately recognized?" — "does this classification match reality?", "is the count reasonable?" — alignment of recognition.

Discussion about a strategy proposal centers on "is the priority or methodology reasonable?" — "why start there?", "are there other options?" — alignment of judgment.

These are different layers of discussion. Mixing them in the same room produces a muddle. You're supposed to be doing fact-alignment, but before you know it the conversation has slid into strategy.

By splitting into separate documents, each discussion gets to happen at its proper depth.

Reason 4: My own freedom of thought changes

This was the biggest reason for me personally.

When you write under the stance "let's organize the current state because we want to automate," the analysis tends to become "evidence-hunting for automation." Areas not suited to automation, or improvement opportunities orthogonal to automation, gradually fall out of view.

When I temporarily scrubbed the automation context and looked at the current state neutrally, something landed cleanly. Seeing "cross-cutting common post-processing" surface as one strong pattern — that probably only happened after I took off the automation premise and looked at the data flat.

The writer's premise was lowering the resolution of the analysis. Taking it off mid-flight was, honestly, a bit lucky.

The document structure after redesign

In the end, the document structure settled like this:

documents/release/
├── deployment_patterns.md       ← Main (neutral current-state material)
└── deployment_patterns/         ← Per-pattern detail
    ├── pattern-1.md
    ├── pattern-2.md
    └── ...

The main contains observable facts only. Classification diagrams, summary tables of patterns, trends (half-year transitions), the analysis's evidence and its limits. That's it.

The strategy proposal will get its own separate document. "This is the current state" gets shared first; "therefore I want to do this" comes next — a two-step structure.

What's next

The automation-strategy discussion is still ahead.

A strong candidate for first focus is the cross-cutting "common post-processing" pattern. Since it runs in every release regardless of type, the effect spreads widely. On the other hand, there are human judgments mixed in that resist formalization, so what to put in a CI/CD job, what to delegate to an AI agent, and what humans need to call — that design is yet to be worked out.

Once the actual job specs are concrete, I'd like to write that up separately.

Reflection

The bigger lesson for me from this work wasn't the act of having AI read a large set of documents — it was that I paused mid-write and re-asked "what am I writing this document for?"

"Let's organize the current state because we want to automate" and "let's just look at the current state as it is" sound similar but produce very different artifacts. The former is pulled toward "evidence-hunting for automation"; the latter focuses on neutral observation.

Noticing the misalignment mid-write was probably partly luck. If I'd decided "they should be separated" at the outset, I probably wouldn't have noticed. The order was: mix them, write them so mixed that friction emerges, and only then understand what splitting means.

When writing a document, re-ask "what is this document for?" partway through. Have the courage to delete a chunk of what you've already written. Each time, it stings a bit — but when "deleting makes it cleaner," deleting is usually faster in the end. That's the sensation that landed deeper through this work.

Going back, even when it looks like a detour, often gets you forward faster. I'd like to remember that sensation a little earlier next time.

Related Books

Here are recommended books for those who want to learn more about documentation design, AI-driven analysis at scale, and release automation like in this case.