The easy part and the hard part
Getting prompted to document something — whether by a teammate, a checklist, or WKFGo's MCP server asking after a task closes — solves the "when" problem. It doesn't solve the "what." Say yes to "should I write this up?" and you're immediately facing a blank page. Most wiki rot doesn't come from too few pages; it comes from pages nobody can use, written by someone who said yes but didn't know what to put down.
The test: would this survive the code changing?
A useful heuristic: if the surrounding code changed completely tomorrow, would this page still be true?
Passes the test — write it down:
- Why a non-obvious approach was chosen over the obvious one ("we don't batch these writes because the queue provider caps batch size at 10, and we hit that in production twice")
- A constraint that isn't visible in the code itself (a rate limit, a contractual SLA, a regulatory requirement)
- The result of an investigation, even a dead end ("we tried X, it doesn't work because Y — don't retry this without changing Y first")
- A decision with real tradeoffs, and what you gave up
Fails the test — this belongs somewhere else, or nowhere:
- How the current code works, step by step — that's what the code itself is for; a wiki page duplicating it just goes stale
- Status updates ("finished the migration, all good") — that's a comment or a changelog entry, not durable knowledge
- Anything that changes as often as the code around it
Write for someone with zero context
The person reading this page later — possibly an AI agent doing the reading, not a human — doesn't have the conversation you had in your head while working. Two habits fix most of this:
State the constraint before the solution. "The queue caps batches at 10, so we chunk writes" reads correctly even out of order. "We chunk writes because of the queue" makes the reader hunt for what "because of the queue" means.
Name what you rejected, not just what you picked. "We use polling, not webhooks, because the target service doesn't support them" tells a future reader not to re-propose webhooks. Just documenting "we use polling" invites the same debate again in six months.
A worked example
Bad wiki page: "Updated the retry logic in the payment worker." True, but useless a month from now — it's a changelog line, not documentation.
Better: "Payment worker retries failed charges up to 3 times with exponential backoff, capped at 30s. We don't retry on 4xx responses — those are permanent failures (bad card, insufficient funds) and retrying them just delays the user-facing error. Only 5xx and timeouts are retried."
The second version survives someone rewriting the retry loop next year, because it documents the rule, not the code.
How this connects to MCP
When an AI agent working through MCP finishes a task and WKFGo asks whether to document it, the agent has real context to draw from — the actual constraint it hit, the actual alternative it considered. That's a better starting point than a human trying to reconstruct the reasoning from a diff a week later. It's still worth a quick read before you approve it; an agent's first draft benefits from the same "would this survive the code changing" filter as anyone's.
FAQ
Should every task get a wiki page? No — most tasks are routine and leave nothing worth a durable record. The question is whether this specific task hit a non-obvious decision, constraint, or dead end.
Where do routine "what changed" notes belong? Commit messages and the task's own comment thread — both already exist, both are naturally tied to the work, neither needs a wiki page.
How long should a wiki page be? Short enough that someone reads the whole thing. A five-paragraph decision record beats a thirty-page architecture doc nobody opens.
What if the decision turns out to be wrong later? Leave the page and add a note — a superseded decision with its reasoning intact is still useful; it tells the next person why the old approach seemed right at the time, which usually explains something about the new one too.
Bottom line
Being asked to document is a trigger. Knowing what to write is a skill: capture the constraint and the rejected alternative, not the mechanics the code already shows.