Short answer
#What evidence means here
- Evidence
- A record of where a finding came from: a repository path, a line range, a symbol, a configuration key or a document, together with a short summary of what was there. Evidence never contains the source itself — a locator and a sentence, not a copy.
- In plain terms The receipt for a statement — where it was found, so somebody else can go and look.
This is a small idea with a large consequence. It means a technical statement about your system stops being a matter of trust in whoever wrote it, and becomes something a person can settle in a minute by opening a file.
#Why it matters more than it sounds
The failure mode it removes is specific, common, and expensive.
Ask any capable engineer — or any capable coding agent — to explain a system they have just read, and you will get a fluent, well-organised answer. Some of it will be exactly right. Some of it will be a reasonable inference from naming, framework convention and shape. Both parts arrive in the same voice.
For a reader who cannot tell them apart — an owner, a new CTO, a team taking the system over — that is not a small problem. They will make a decision that depends on which half a particular sentence came from, and they have no way to find out.
Evidence is what makes that separable. The sentence "payments are retried three times" either has a file and a line range under it or it does not, and the reader can see which.
#The anatomy of a claim
Inside a 1ADK project, a claim is not a paragraph. It is a small structure with four parts, which is what makes it possible to compare two analyses and to say that a claim is no longer supported.
| Part | Meaning | Example |
|---|---|---|
| About | The thing the claim is about | The "create payment" operation |
| Predicate | Which property is being described | Idempotency |
| Value | The statement itself, in readable words | "Repeating a request with the same reference returns the first payment." |
| Evidence | Where that was established | app/Services/PaymentService.php lines 40–88 |
#Fact, observation, inference
Three different kinds of statement, kept apart rather than blended.
Every claim also records how it came to be believed. This is the distinction most technical documents lose, and it is the one that matters when somebody is deciding whether to act.
- Observed — this was read directly in the system. The strongest kind: the code does this.
- Declared — somebody stated it. A README, a comment, a specification, a person. Worth recording, and not the same as observed: a declaration can be out of date while remaining perfectly legible.
- Inferred — derived from convention, naming or shape rather than read directly. Often correct. Never to be treated as observed.
A gap between declared and observed is one of the most useful things a technical picture can surface: it is the specification saying one thing and the software doing another, which is exactly where expensive surprises live.
#What confidence is and is not
Claims carry a confidence level — high, medium, low. It is a statement about how firmly the evidence supports the claim, and nothing else.
Not a score
Confidence is not a percentage, not a health rating and not a number to be averaged into a dashboard figure. "Your system scores 73/100" is a sentence that means nothing and hides everything that would have been useful. 1ADK does not produce one.
The related idea is freshness: how long ago the evidence was collected, and whether the latest analysis still supports it. A high-confidence claim from an analysis run seven months ago is a high-confidence claim about seven months ago.
#A claim taken apart
CLAIM Repeating a request with the same reference returns
the first payment rather than creating a second.
ABOUT Create payment · POST /api/payments
PERSPECTIVE Observed
CONFIDENCE High
EVIDENCE app/Services/PaymentService.php:40-88
"Where the payment is created."
RELATED A claim that contradicts this one was declared in
UNKNOWN · No test was found that exercises the
repeated-request path.Notice what the reader can now do that they could not before: disagree specifically. "I opened those lines and that is not what it does" is a conversation that ends in a correct answer. "I don't think that's right" is not.
#Why this matters more with AI in the loop
Coding agents have made it far cheaper to produce a plausible technical explanation of a system. That is genuinely useful and it changes the economics of understanding software. It also means the supply of confident, well-written, partly-wrong technical documents has increased enormously.
1ADK's position is not that agents should be distrusted — the product is built on one. It is that the output of an agent should be checkable, and an unchecked assertion should look different from a checked one. That distinction is the entire reason the analysis instruction demands locators, forbids source code in the output, and requires unknowns to be reported rather than filled in.
There is a related discipline for owners whose systems were largely written by agents: AI-built software covers what changes when nobody in the company ever held the whole picture.
#What evidence does not prove
What this does not do
- That the code is correct. Evidence shows what the code does, not whether that was the intention.
- That the analysis found everything. A claim with evidence is well supported; the absence of a claim is not evidence of absence — that is what unknowns and coverage are for.
- That the evidence is still current. A locator points at a file and a line range as they were at a particular commit. Lines move.
- That a human read it. Evidence records where a finding came from, not that somebody senior agreed with it. Human review is a separate, explicit state.