It's not a discipline problem

Every engineering team has had this conversation: "we need to document better." Someone writes a wiki policy. Everyone agrees. Three months later the wiki has the same four stale pages it always had, and the reason behind last quarter's tricky auth fix lives in exactly one person's memory.

The usual read is that the team is undisciplined. It isn't. Documentation is a timing problem, not a willpower problem — and most teams are solving it at the wrong moment.

The half-life of "why"

Right after you finish a piece of work, you know exactly why you made every choice: the tradeoff you considered and rejected, the constraint that forced the ugly workaround, the thing that looked simple and wasn't. That knowledge has a half-life.

A day later, you remember what you did but the tradeoffs have blurred. A week later, in code review, you can reconstruct the reasoning if pushed, but it takes effort. A month later, at the retro where someone finally asks "why is this built this way?" — you don't remember there were tradeoffs at all. You just say "it made sense at the time."

Nothing in a typical workflow asks the question while the answer is still cheap to give.

Where the documentation actually goes

It doesn't vanish — it just ends up somewhere nobody can find it later:

Every one of these is a real record. None of them is durable, searchable, or attached to the work it explains.

The two things that actually work

Capture at the moment of work, not after. The cheapest time to record a decision is the five minutes after you made it — not the retro, not the postmortem, not "whenever someone gets around to writing a wiki page." Any workflow that defers documentation to a later ceremony is deferring it to a moment when the knowledge has already decayed.

Make writing it down cheaper than not writing it down. A blank text box titled "add documentation here" loses to a deadline every time. A direct yes/no question — "want me to write this up?" — asked at exactly the right moment, doesn't.

Where an AI coding agent changes the equation

A meaningful share of code now gets written by an AI agent working inside an editor like Claude Code or Cursor. That agent finishes a task with the full reasoning still in its context window — the same fresh, cheap-to-capture state a human developer is in for about five minutes after shipping.

That's the moment worth catching. WKFGo connects to these agents over MCP and, right after a task wraps up, has the agent ask you directly: write this up as a wiki page? It never writes anything unasked — see how MCP documentation works for the mechanism.

Common objections

"We already have a wiki nobody uses." The wiki isn't the problem — the missing trigger to write in it is. A wiki with no prompt to add to it decays the same way an empty one does.

"Documentation goes stale anyway." How-to guides go stale. A decision record — we chose X over Y because Z — doesn't go stale, because it's a historical fact, not an instruction. It stays useful even after the code around it changes.

"This is a process problem, not a tooling problem." True, but tooling is how you make a process survive contact with a deadline. A policy nobody enforces isn't a process — it's a wish.

FAQ

Should documentation come from a person or an AI agent? Either — the timing matters more than the author. A human who writes a decision down five minutes after making it beats an agent that writes it a month later, and vice versa.

Does more documentation always help? No. A wiki full of stale how-to guides is worse than no wiki, because it actively misleads. The goal is a small number of accurate decision records, not exhaustive coverage.

What's the smallest version of this that works? One habit: whenever a task or a decision closes, someone (or something) asks "should this be written down?" before the context is gone. Everything else is refinement.

Bottom line

Documentation debt isn't a motivation problem — it's a missed window. Catch the reasoning while it's still in someone's (or something's) working memory, and the wiki takes care of itself.