How do you document what nobody knows about a system?

#What an unknown is

Unknown

A recorded question that an analysis could not settle, carrying the reason it could not be settled, what it is about, why it matters, and a priority. It is a first-class result stored alongside the claims, not a footnote and not an error.

In plain terms A written-down question about your own system that nobody has answered yet — with a note on why it matters.

The analysis instruction is explicit with the agent about this: an empty unknowns list after one pass over a real system is a guess, not a finding. An agent that reports nothing it was unsure about has almost certainly filled the gaps with inference and stopped distinguishing them.

#Not found is not absent

One sentence that changes how a technical picture behaves.

Suppose an analysis does not mention a backup process. Three quite different things could be true:

1. There is no backup process.
2. There is one, and it is configured somewhere the analysis did not look.
3. There is one, and the analysis did look, but could not tell what it does.

A document that simply omits the topic makes all three look like the first. This is not a hypothetical failure — it is the ordinary way technical documents mislead people, and it does its damage precisely at the moments the document is being relied on most: a handover, a supplier change, an incident.

So absence of a finding is never rendered as absence of a thing. Where the analysis cannot establish something, it says so, and says which of the three situations it is in.

#The kinds of unknown

Each unknown also carries a priority — low, medium or high. There is no level above high on purpose: something more urgent than that is a risk for a person to raise with another person, not a line in a report.

#What one looks like

HIGH    What happens to a payment the provider never confirms?
        About      Billing service
        Reason     Not established — no reconciliation path was found
        Matters    Money may be taken with nothing recorded against it.

MEDIUM  Where does the nightly export write its file?
        About      Nightly export
        Reason     Out of scope — the destination is configured outside
                   the repository
        Matters    Nobody can say who receives customer data every night.

LOW     Is the "legacy" prefix on four modules still meaningful?
        About      Four modules
        Reason     Needs a person — this is history, not code
        Matters    A new team will avoid or rewrite them on the strength
                   of a word.

#Why an owner should want these

It is counter-intuitive: you are paying for a picture and it hands you a list of things it does not know.

Three reasons, in the order they usually become obvious.

1. It is the shortest possible list of questions to ask

   A developer who is leaving has limited time and infinite context. A prioritised list of the specific things nobody else can answer is worth more in that final week than any amount of “please write documentation”.

2. It tells you how much of the picture to trust

   Twelve unknowns concentrated around payments is a different situation from twelve spread evenly, and both are different from none at all. The distribution is information about your system.

3. It is the thing that shrinks

   An unknown answered is progress that can be seen. Over several analyses the list becomes a record of understanding being recovered — which is a far better measure of a handover than the number of pages produced.

#How an unknown gets closed

Two ways, and both are recorded rather than silently applied.

• A later analysis answers it. The next scan finds what the earlier one could not — usually because coverage widened, or because somebody wrote the missing thing down inside the repository.
• A person answers it. The reconciliation question above is not in the code. Somebody knows, and the answer becomes part of the record with the person attached to it.

The reverse also happens, and it is worth expecting: an analysis can open a new unknown about a part that was previously understood. That is not a regression in the tool. It usually means the system changed in a way that made a previous claim unsupportable, which is exactly the thing you wanted to be told about.

#Coverage: the other half

Unknowns say what could not be established. Coverage says what was looked at. You need both, and the second one is what makes a comparison between two analyses honest.

Every analysis records, per scope, whether it was covered completely, partially, or not at all — and what was deliberately excluded. This is why 1ADK can distinguish "this component was removed" from "this analysis did not look there". Where coverage is only partial, nothing is reported as removed, because it cannot be.

Change history depends entirely on this. Without coverage, every narrow analysis would look like a demolition.

#What this does not fix