The Design Document Describes a Proof of Concept That Died

Two pages describe the migration lock. An architecture page and its low-level design, both authoritative, both detailed, both internally consistent.

None of the metadata they name exists in the org.

A Document Can Be Coherent and Still Be Fiction

The pages specify a field family, a custom permission, a custom metadata type, triggers and an admin LWC. Read together they hang together — the field family carries the state, the permission grants the override, the metadata drives the configuration, the triggers enforce it, the LWC lets an admin work with it.

Search the org's metadata for those names and you get nothing.

What is actually deployed is a different field family, with different names, doing the job a different way. Neither page carries a banner, a status, a strikethrough or a single sentence saying it documents an approach that was abandoned.

So the most authoritative-looking description of the feature describes something that was never built, and there is no marking anywhere to tell you that.

This is a different failure from the one most review checklists are aimed at. A document that contradicts itself announces its own problem — two sections disagree, and you can find it by reading carefully. This document has no internal problem at all. It is perfectly consistent about a system that does not exist. Reading harder will never surface it.

Why Dead Proofs of Concept Leave Live Documents

A proof of concept produces the same artefacts as a real build. Someone designs it, someone writes it up, someone reviews the write-up. The pages get created early, while the idea is still the plan.

Then the approach gets dropped. That decision happens in a conversation, a stand-up, a comment thread — somewhere fast and verbal, because dropping an approach is a technical judgement, not a deliverable.

Nobody goes back to retire the page. Retiring it is nobody's ticket, it takes a permission somebody may not have, and at the moment of the decision it is obviously understood by everyone in the room that the approach is dead. The understanding is real and it is entirely undocumented.

What survives is asymmetric. The abandoned idea keeps its full documentation set. The shipped solution has a ticket comment.

That is the state I found: a full-text search for the deployed field name returns zero results in the wiki. The only written description of what actually runs in production is a comment on a ticket.

The Search That Should Have Been Obvious

Searching for the field that exists, rather than reading about the field that does not, is a thirty-second action.

It is also not a natural one, because it inverts the direction everybody works in. The normal flow is document to system: read the design, understand the intent, go look at the org, write the tests. Every step of that flow starts from the page.

Running the search the other way — take a name from the org, ask what the documentation says about it — feels backwards. It is the check that catches this, and it is the check nobody schedules.

Zero results for a deployed field name is not an inconvenience. It is a finding, and it is worth writing up as one. It means the thing running in production has no reviewed description, which is a problem long after your release ships and long after you have moved on.

Match the Names Before You Write the Tests

Here is the rule, and it is deliberately mechanical.

Before preparing tests from a design document, take every field, permission, class and component name it cites and confirm each one exists in the org's metadata.

Not "confirm the design is implemented." Not "assess whether the approach matches." Just: does this name exist. It is the cheapest check available to a tester and it is the only thing separating testing the system from testing an idea somebody once had about the system.

In practice it is a pass through the document with a list, and then a pass through the org with the list.

• Extract every named artefact, not every concept. Fields, permissions, metadata types, classes, triggers, components — anything that has an API name and could be searched for. Concepts and behaviours come later; names are what you can verify in seconds.
• Check each name against the org, not against another document. Metadata search, setup, a describe call, a deployment manifest. Another page agreeing with this page tells you only that both were written by people who read the same design.
• Treat any miss as a stop, not a footnote. One missing field is a typo. A whole family missing, plus its permission, plus its component, means the document describes a different solution and everything you were about to write against it is void.

The third bullet is where the time gets saved. One mismatch is a chat message. A cluster of them is a different artefact, and reading it as a cluster is what stops you building a week of test data for a mechanism that does not exist.

What This Does to Your Test Basis

The uncomfortable part is what you are left with once the pages are disqualified.

The real solution is described in a ticket comment. That is your test basis now. Not a reviewed design, not something with an owner and a version history — a comment, written to explain a change to whoever was watching that ticket that day.

You can still test from it. You read it, you query the org for what actually got deployed, you reconstruct the intended behaviour from the two together, and you write down what you concluded so the next person has something better than you had.

But you should say out loud that this is what happened. A feature whose only written description is a ticket comment carries a specific risk that has nothing to do with your test coverage: the next change to it will be designed by someone who found the wiki pages first.

And they look right. That is the whole problem. They are well written, they are detailed, they are consistent, and the only thing wrong with them is that they describe a road not taken — with no sign at the junction.

Of the design documents you are testing against right now, how many name a field you have actually confirmed exists?