Your product changed. What has to change in the AI system?

You updated the product docs. Somewhere, an agent is still confidently explaining the old product.

The maintained source is correct. The saved prompt isn't. Neither is the example someone copied into a workflow three months ago.

Meanwhile, a scheduled article is patiently waiting to publish yesterday's promise.

“Living documentation” sounds like a property of the document. In practice, it's a maintenance job across everything that consumes the document. The useful question is what happens after the source changes.

Follow one change until the trail gets uncomfortable

Take a fictional export feature. Version 1 returned a download URL immediately. Version 2 starts a background job: the first response contains a job ID and a queued state; later it becomes ready with a URL, or failed.

The new product behavior is settled. The question is which parts of the AI system still assume the old one.

A help page saying “download immediately” needs an edit. So does a workflow that looks for a URL in the first response and tells the customer the file is ready.

Fixing the sentence won't fix the parser.

Microsoft's asynchronous request-reply pattern separates accepting work from completing it. Your maintainer needs the actual contract, including waiting and failure behavior, rather than a general instruction to “handle exports better.”

Start with scope

Does v2 apply to every integration? Are some customers still on a supported v1 path? When did the change take effect, and who can confirm it?

Keep valid v1 guidance available to v1 users. Label it well enough that a v2 workflow doesn't mistake it for current instructions.

Then search for more than links to the source. Search the old wording, response fields, and workflow names. Inspect a real run. Copied assumptions often lose their provenance long before they lose their influence.

Consumer	Who owns the update	What would establish that it caught up?
Product brief and help source	Product lead	Approved v2 behavior and scope in the identified revision
Retrieval and saved context	Knowledge maintainer	The actual v2 passage is returned or loaded
Instructions and export adapter	Workflow owner	Queued, ready, and failed states work correctly
Examples and tests	Workflow owner	Expectations match the contract; results inspected
Help pages and generated material	Content owner	Correct guidance at the destination people use

Those are responsibilities, not five new hires. A small team may assign several to one person.

Put the update mechanism beside each dependency: direct file read, scheduled sync, copied prompt, manual import. Operational docs become systems when you account for their readers, including the software readers.

Separate stable explanation from changing facts where that helps. But if the positioning promises instant downloads, it needs revision too. Calling something “evergreen” doesn't make it immune to the product.

Give “done” an observable meaning

The W3C's guidance on version indicators and history gives consumers a way to distinguish versions and understand changes. Apply that principle to the update record.

For each dependency, name the expected revision, owner, state, and evidence. “Edited” means someone changed it. “Verified” means the relevant check ran against the intended version.

An index refresh can still be pending after the product document is approved. Keep that row pending.

Metadata can describe allowed edits, but it doesn't enforce them. Claude Code's instruction documentation distinguishes context from enforced configuration. A file saying “only change these sections” isn't a technical write restriction.

Use an implemented control or review the proposed diff where the boundary matters. That's part of moving from knowledge storage to an operating system: the instruction connects to an action someone can inspect.

Inspect the input the agent actually received

The current file in your editor is not proof of what another process loaded.

In Amazon Bedrock's knowledge-base workflow, source changes require synchronization. Some vector stores can also have a delay between completed ingestion and query availability.

Other systems have other mechanisms. Find yours, run the relevant query, and inspect the returned passage and source identity. A completed sync job and a correct answer path are separate checks.

Then look at the assembled input. The workflow may retrieve the right v2 passage while loading an old example that says to return a URL immediately.

Check the instructions, examples, source excerpts, and relevant conversation state that reached the run. That makes “the AI is confused” a much more specific problem.

Use diagnostics appropriate to the loader. Claude Code's context view, for example, reports loaded CLAUDE.md and rules files; directly loaded AGENTS.md files use a separate signal and don't appear in that list.

Absence from one diagnostic isn't evidence about every file type. Loading a file also doesn't prove the system interpreted or followed it correctly.

Don't clear every cache out of frustration

Claude's prompt caching reuses work on matching input segments. It doesn't cache finished answers.

If the application keeps sending an obsolete prompt, the stale prompt is the problem. A separate application response cache or old conversation may require a different fix.

Find the stale representation before choosing the remedy. Otherwise “clear the cache” becomes a ritual performed whenever the system tells an inconvenient story.

Change behavior, examples, and expectations together

For the fictional v2 export, the instruction needs to explain that queued work isn't a completed download. The executable steps need to support that explanation.

Retain the job ID, follow the documented status mechanism, and distinguish ready, failed, and still waiting. A prompt describing patience won't help a parser that requires a download URL in the first response.

Check the success template too. It can keep announcing “your file is ready” after the parser has been repaired.

JSON Schema's conditional validation can require different fields for different states. A ready result needs a URL; a queued result doesn't. Require the state field where its absence should fail, and actually run a compatible validator.

A schema sitting next to the workflow is documentation. It becomes a check when something uses it.

Structural validation still won't prove that the URL delivers the expected file, implement polling, or choose how long the operator should wait. Those need their own behavior and tests.

Test the old assumption where it can survive

Prepare a compatible set of product source, instructions, adapter, and expected results before activating the change. Keep live consumers on a supported path or hold the affected automation during transition.

For this example, useful cases include:

Condition	Expected behavior
v2 job queued	Preserve the job ID and report pending
v2 ready with URL	Validate and check the permitted test export
v2 failed	Report failure and follow the recovery path
Local waiting limit reached	Keep the job unresolved and retain its ID for follow-up
Ready response missing URL	Reject the incomplete result
Unsupported contract version	Hold for a compatibility check

A local timeout doesn't prove the server failed. Check the existing job or follow the service's retry mechanism before creating another one. Otherwise the “recovery” may just produce duplicate work.

Replace obsolete v2 examples. Retain v1 cases where that path is still supported. Unknown versions shouldn't quietly inherit the old behavior.

This is where workflow design and content QA meet. The system needs to do the right thing and describe what it did accurately.

A corrected source isn't a corrected customer experience

Run the updated workflow and inspect its actual result. Does a queued export remain visibly pending? Does completion refer to the right job? Does the customer explanation avoid promising a time the product never guaranteed?

Anthropic's evaluation guidance distinguishes success claims from outcomes. Include cases where the workflow should refuse to announce success.

Then work through material that already exists. Updating the template doesn't repair a scheduled article, a saved support reply, or an onboarding email draft.

Search those surfaces for the old promise. Establish which product version each addresses and what needs correction before its next use.

For a public page, inspect the URL after its authorized release. If the correction is only local, say so. The page people can read is the destination that matters.

Preserve history without serving it as current instructions

GOV.UK's content-retirement guidance distinguishes updating, retaining withdrawn material, and removing content.

A dated v1 announcement may remain useful history. Still-supported v1 help remains useful guidance for its audience. Neither should become the answer to a v2 question by accident.

Adding a “historical” label doesn't automatically change retrieval. Verify the filter, selection rule, or removal mechanism that gives the label meaning.

Recovery can't make the old product true again

Keep prior versions and a record of which components work together. Test recovery in an appropriate environment before needing it.

If v2 remains live and the workflow breaks, restoring a v1-only parser doesn't restore immediate downloads. Restoring the old help text makes the explanation wrong too.

Pause the affected automation or apply a compatible correction. Return to a v1 path only if the product still supports it and the consumer can use it appropriately.

A saved configuration proves that a configuration existed. It doesn't prove the old service still does.

Use one change record to track the fact, scope, consumers, owners, expected revisions, checks, and unfinished work. A deliberate decision to retain a historical announcement is different from a broken workflow waiting for repair.

Trigger that review when a relevant release, deprecation, contract change, or failure happens. Periodic reviews can catch omissions, but a monthly reminder is a poor substitute for noticing today's product release.

When you find a missed consumer, add it to the next review. That's feedback becoming a workflow improvement, rather than another warning paragraph in an enormous prompt.

Take one recent product change and follow it to an output somebody relies on. If the trail disappears, you've found a concrete maintenance job. We can help build that path so the next change has somewhere to go.