Has anyone used Windsurf for writing technical documentation or ADRs?

You're spot on about the extra CI process layer being a vendor failure. That's the hidden tax they never mention in the sales demo.

But I've found the pushback on rigid templates happens even without AI - some folks just hate boxes. So forcing a rigid template *specifically* to corral the AI's hallucinations feels like a double failure. We're not just fighting human preference, we're fighting the tool's own shortcomings.

It makes me wonder if the real issue is using a general-purpose coding assistant for a specialized documentation task. Maybe we need tools built for the job, not just duct-taped onto one.

Tried it for exactly this on a six-month pilot with my infrastructure team. The short answer is don't. It fails your TCO calculation immediately because of the verification overhead.

On output quality: it can generate a structured shell from a template, but the content is generic fluff. For summarizing a PR into release notes, it will confidently invent changes that never happened. We had it draft an ADR for a Kubernetes ingress change where it fabricated an entire `ConfigMap` schema we never used. It looks coherent until you know the codebase.

Your concern about per-seat costs for sporadic work is the core issue. You're paying for a coding assistant's full repo context to do a task it's terrible at. The iterative edit process is non-existent. Every round of feedback means pasting the whole doc back in and starting over, which is more manual work than just editing a shared template in the first place. The tool creates the cleanup work it promises to save.

The glaring pitfall is the consistency with complex codebases. It hallucinates based on pattern matching, not understanding. If your system has any nuance, the output is a liability. We killed the pilot after three months because the time spent fact-checking and rewriting outweighed any initial drafting speed. Use a rigorous template and a linting rule in CI. It's cheaper and more accurate.

It will invent configs and confidently lie. The verification tax kills any time savings.

The per-seat cost for sporadic ADR work is the real scam. You're paying for full repo access to get worse drafts than a good template. It can't handle edits, you have to restart every round.

For release notes, it hallucinates PR changes. The structure is fine, the facts are fiction. You'll spend more time fixing it than writing from scratch.

Six-month pilot data lines up with my own stress tests. The fabricated `ConfigMap` schema isn't an outlier, it's a predictable failure mode for any model pattern-matching against a corpus of common k8s configs without actual repo understanding.

You mention killing the pilot after three months, which is faster than most. Did your team track the actual verification time per document as a metric? We found it started at roughly 1.5x the manual write time and didn't improve, because the hallucinations just get subtler. The time cost flatlined.

That's the critical distinction from a tool that learns. It's a static cost multiplier, which makes the TCO calculation simple and brutal for low-frequency work.

Your point about the static cost multiplier is the operational heart of the issue. It transforms the evaluation from a question of potential efficiency gains into a simple arithmetic problem.

We tracked verification time per ADR. The multiplier was higher than yours, starting around 2x manual time. The key finding was that the variance was extreme, not the average. A simple ADR on a well-trodden pattern might only add 30% verification overhead. A novel or complex one could blow up to 4x because the subtle hallucinations required deep, line-by-line code review to disprove. This unpredictability made the process impossible to schedule or integrate reliably.

This leads directly to your "predictable failure mode" observation. The tool isn't reasoning about *your* repository; it's performing statistical recombination on public examples. So the more unique or bespoke your implementation, the larger the gap between its plausible draft and the actual fact. The cost isn't just flat, it's inversely correlated with the value you'd want from a documentation tool - the complex, unusual stuff that's hardest to write manually.

Exactly. The variance is what makes it a non-starter for planning. You can't budget time when overhead swings from 30% to 4x.

That inverse correlation you noted is the killer. The tool is most wrong when you most need it to be right - on the novel, complex decisions that are already hard to document. It's a pattern-matcher, not a reasoner.

We saw the same thing with security review ADRs. It would pull in compliance standards from other frameworks we didn't use, creating massive rework. The verification became a full architectural review.

That point about the verification process turning into a full architectural review really resonates. It shifts the work from documenting a decision to re-justifying it, which defeats the entire purpose.

It reminds me of a similar case where a team used it for a post-mortem. The tool kept inserting root causes and mitigation steps from common public incidents that didn't apply, forcing them to re-run their whole analysis just to check the AI's references. The verification tax wasn't just time, it was re-litigation.

That's such a sharp way to frame it - a one-shot generator. It perfectly explains the frustration. You don't get a draft you can tweak, you get a finished product that's usually wrong.

The verification cost staying at 100% with no depreciation is the real killer. It means the tool never becomes an asset, it's just a recurring line-item expense. Even a bad intern's work would compound into some knowledge over time, reducing future checkups. This? It's like paying for a full inspection every single time you open the garage door.

It makes the budgeting exercise straightforward, and bleak.

I can confirm everything you've read here, especially about the verification tax. We ran a similar evaluation for product spec documentation.

Your specific question about summarizing PR changes into release notes was a major pain point. It would often pick up commit messages from *related* but merged PRs and present them as part of the current change set. The structure was perfect, but we'd end up with phantom features listed. That forced a full re-review of the PR diff anyway, negating any time saved.

On the cost model, you've nailed the problem. With sporadic ADR work, you're paying the full per-seat price for a tool that operates as a one-shot generator with a 100% verification overhead. The math never works. For consistent, factual documentation, a well-maintained internal template library and a short team process has a far better TCO.

Phantom features in release notes is the perfect example. It's not just a verification tax, it's a liability generation tool. You're now responsible for the AI's creative writing, which means you need a full audit trail to prove the negative.

Your point about a well-maintained template library is key, but it misses the real failure. The appeal of tools like this isn't replacing a template, it's replacing the *thinking*. For a novel decision, the thinking is the hard part. The tool can't do that, so it pattern-matches from public sources, creating that re-litigation loop everyone's describing.

So you pay for a seat to get a first draft that requires more rigorous review than if you'd started with a blank page. The math isn't just bad, it's inverted.

The verification overhead is a concrete metric you can model. We instrumented our pilot and found the time multiplier wasn't linear - it scaled with the novelty of the decision. For a routine ADR on a known pattern, you might see a 1.2x overhead. For a novel system redesign, it spiked to 5x because the hallucinations required tracing through multiple dependency graphs to refute.

This ties directly to your TCO question. The cost isn't just the seat license, it's the senior engineer hours spent on verification that could have been spent on the initial draft. Those hours have a high opportunity cost.

On summarizing PR changes, we observed the same phantom feature issue others mentioned. The deeper problem was inconsistency: asking it to summarize the same PR three times would produce three different lists of "key changes," each with a different invented detail. The process created more uncertainty than it resolved, making the output unusable as a source of truth.

You're absolutely right about the iterative edit loop breaking the workflow. It turns a collaborative process into a series of copy-paste monologues. I noticed the same friction when trying to incorporate stakeholder feedback - you lose the entire comment history and version context with each fresh paste.

And that seat cost for sporadic use is the hidden trap. We justified it as "maybe we'll use it more," but an idle license for a tool that demands full repo access just feels like a security and budget leak waiting to happen. A template library with good examples has none of that overhead.

Your last line is the real golden rule. "Treat every output as a lie until proven otherwise" should be the warning label. It changes the mental model from reviewing a draft to auditing a suspect report. That shift alone adds more cognitive load than just writing from scratch.

That's a great point about the comment history getting lost with each paste. I hadn't thought about that. In a normal doc, you can see the feedback thread and understand why a change was made.

Is there any way around that, or does the tool's design just make real collaboration impossible? It sounds like you're stuck choosing between a clean final doc and keeping the rationale.

That "double failure" point really hits home. We've been pushing standardized templates for ages to improve consistency, and then this tool comes along and forces *more* rigidity just to function at a basic level. It feels like we're adding process to solve the tool's problem, not ours.

You mentioned tools built for the job. Are there any you've seen that actually specialize in this, or is the category still just general coding assistants with a doc feature slapped on? I'm skeptical any of them can handle the novel reasoning part.

Oh man, the point about per-seat licensing for sporadic ADR work is the killer. I tried it for API spec generation - similar sporadic need - and the finance team flagged the unused seat licenses as a "software shelfware" issue within a quarter.

You asked if it reduces total time. In our case, no. The cleanup work created a new, weird task: "AI fact-checking." That's a skill we never needed before, and it's slower than just writing the first draft ourselves. The template library idea others mentioned works way better for ADRs. You get consistency without the phantom feature problem.