The grammar, entire
- field:value
- Match a field.
capability:curable
- a b
- A space means AND.
capability:curable reach:<0.5 — curable, and reaching under half of patients.
- -term
- A leading minus negates.
-blocker.kind:knowledge — nothing here is waiting on science.
- field:(a OR b)
- Alternation within one field.
blocker.standing:(alleged OR disputed)
- field:>n
> >= < <= = on numeric fields. Numbers take k, M, B: deaths:>100k
- "two words"
- Quotes carry spaces, nothing more.
quadrant:"known & treatable"
- word
- No field means free text over the whole record, prose included.
lithium
Two rules that save you remembering things
- the field decides
- How a value matches is a property of the field, not of how you quoted it. An enum field is always exact; a text field is always substring. So
name:hepat finds hepatitis C and capability:cur is an error that names the four legal values — which is what you want in each case.
- lists mean some
- A record has many blockers, so
blocker.kind:cost asks whether some blocker is a cost blocker, and -blocker.kind:cost therefore means none is. For every — "all blockers are knowledge" — use the derived flag only_knowledge_blockers:true; the register names that concept, so it is computed once in check.py rather than spelled out here.
A wrong value is answered, not ignored
capability:cured does not return nothing. It says
“capability has no value cured — did you mean curable? valid: curable · managed ·
partial · unsolved”, and the valid list is read off the data, so it cannot drift from what is
actually loadable. Terms that fail are reported and skipped; the rest of the query still runs, and
the count of what was dropped comes back with it.
Not here yet
- OR across terms
- Deliberately absent, with parentheses. Alternation inside one field covers most of it and has no precedence to get wrong; boolean algebra across terms is the half of this syntax people reliably misread. Type it and the register says so and tells you what does work. It gets built when a question worth asking forces it — and it will be obvious which question that was.
Worked examples
Click one to
run it. Each is a plain string you could have typed — which was already
true when these were buttons on the tool, and is the reason they could be
moved here without losing anything.
Every field
Fields marked derived are calculated by check.py from the YAML, never stored.
That is what makes them arguable: a stored verdict is an opinion, a derived one is a calculation
you can check. src:recall matches every record in the register today.
What the words mean
Every derived word in the results table is a term of art, and a public register that does not define its own vocabulary invites exactly the misreading it was built to prevent.
Reading a record
- capability
- What medicine can do at its best, for anyone. Derived from the intervention rung. It says nothing about how many people get it.
- terms
- What the treatment costs you if it works. clean · costly (takes something permanent) · harsh (permanently disabling in its own right).
- residue
- What the disease leaves behind in someone the treatment cured — damage already done that no cure reaches. Tuberculosis is the case that forced the field: the drugs take almost nothing, and a large share of cured patients keep permanently scarred lungs.
- restored
- Are they back to the state they were in before any of it? Derived from terms and residue together, because those are the two ways the answer is no. restored · cure-costs (the treatment took something) · disease-residue (the treatment worked and the damage was already done) · both · n/a — nothing to be restored from, because there is no capability at all. n/a is not restored.
- reach
- efficacy × access — the fraction of patients for whom the capability is actually real.
- delivery
- reach, in words: delivered ≥0.8 · mostly ≥0.6 · partly ≥0.3 · barely ≥0.05 · undelivered below that.
- quadrant
- Which cell of is the mechanism known? × what does treatment achieve? a record falls in — six cells, not four. Not a verdict on the disease. The field kept the name
quadrant after it grew a third column, because queries use it. See below.
The map, and what it does not say
The second axis is the intervention ladder in three bands: the course is held or ended (suppressive, curative) · slowed (disease-modifying) · unchanged (symptomatic, none). It used to be a yes/no, which filed ischaemic heart disease and stroke — the first and third largest causes of death on Earth — as nothing can be done.
- known & treatable
- The mechanism is understood and something demonstrably works — a treatment or a prophylaxis. Measles and rabies sit here on the strength of a vaccine, with no treatment at all. This is not "solved." It says nothing about whether anyone is cured, what the treatment costs them, or whether it reaches a single patient. Breast cancer and Crohn's disease both sit here.
- known & modifiable
- Understood, and treatment slows the course without holding or ending it. Ischaemic heart disease and stroke: the coronary death rate in wealthy countries has more than halved since about 1980, and the atherosclerosis still progresses. This cell exists because filing those two as untreatable was wrong.
- engineering problem
- Understood, and treatment does not change the course at all. Huntington's: the exact cause has been known since 1993 and nothing alters it. COPD is here too, and note what that does not mean — bronchodilators genuinely relieve breathlessness; this register measures benefit only as course alteration.
- empirical luck
- Something works and nobody can say why. Lithium in bipolar disorder, effective since 1949, mechanism still unknown.
- empirical foothold
- Something slows a disease nobody understands. No record is in this cell. It is named because the derivation has to be total, and an empty cell is worth reporting rather than hiding.
- frontier
- Neither understood, nor altered by any treatment. Note how much of the world's burden sits here.
The intervention ladder
- none
- Nothing alters the course.
- symptomatic
- Masks the phenotype; the course is unchanged.
- disease-modifying
- Slows it. Does not arrest it.
- suppressive
- Near-normal life and lifespan — treated indefinitely. HIV. Not a death sentence, and not over.
- curative
- A finite intervention ends the disease. Hepatitis C.
The other axes
- mechanism
- established (a causal chain that would survive a refutation attempt) · partial (the chain has a named hole) · correlates (associations, no chain) · none.
- prevention
- Independent of treatment, not a continuation of it: eradicated · prophylaxis · risk-reduction · none. PKU's phenotype is prevented outright and the disease is never cured.
- ongoing
- The burden of being treated — the gulf between one tablet a day and dialysis three times a week.
- efficacy vs access
- Deliberately two numbers. Epilepsy is ~30% drug-resistant in the richest health systems (biology); sickle-cell gene therapy works nearly always and reaches nearly nobody (money). One number could not say both.
Measurement — three questions, not one
- diagnostic
- Is the disease there? objective (a test) · clinical (human judgement against criteria) · complaint (the patient's report is the diagnosis).
- prognostic
- What will it do if left alone? Its absence causes overtreatment — treating people who were never going to be harmed.
- predictive
- Will this treatment work in this patient? Its absence causes futile treatment: the full cost, no benefit, discovered only afterwards.
- n/a
- There is no selection question left to answer — either nothing course-altering to predict a response to, or a treatment that works in essentially everyone. Pan-genotypic antivirals abolished the question for hepatitis C.
Toll, window, strata
- toll
- What the cure takes, permanently — the facial nerve, the bowel, fertility, a second cancer. Not the same as ongoing (the burden of continuing treatment) and not the same as efficacy (whether it works). This is the price of it working.
- residue vs toll
- Two different permanent costs, and the register keeps them apart because the levers differ. toll is inflicted by the treatment — a better treatment reduces it. residue was inflicted by the disease before the treatment arrived — only earlier treatment reduces it, which is why residue and window usually travel together. "Cured" is not one outcome.
- severity
- none · minor (permanent, not life-altering) · major (permanently alters function or appearance) · catastrophic (disabling or life-shortening in its own right). Severity describes the harm when it happens; incidence carries how often.
- window ⧗
- Capability itself depends on catching it in time. Crohn's inflammation is treatable; the fibrosis it leaves is not, because scar is mechanical.
- strata ⧉
- One entity with more than one answer. Breast cancer stage I is cured and stage IV is not — so "is it solved" is a malformed question, not a hard one, and the register refuses to pick a side.
Blockers — why it isn't delivered
- kind
- What is stuck: knowledge · candidate-untested · evidence-incomplete · no-sponsor · regulatory · manufacturing · cost · logistics · diagnosis · adherence · tooling · policy. Different blockers need different people to fix them.
- scale
- Rough order-of-magnitude cost to clear it. Blank for a knowledge blocker, and the asymmetry is the point: knowledge blockers cannot be triaged with money, delivery blockers can.
- standing
- documented (a named trial, price, or dated discontinuation) · alleged (widely asserted, unverified) · disputed · refuted. The register's job is to turn alleged into documented or refuted — a project that only ever finds documented is campaigning, not investigating.
The flags
- ⚑ no champion
- Capability is real, reach is under 0.6, and at least one blocker is documented and not knowledge. The science is done and nobody is carrying it.
- ⧗ window
- Catching it late changes what is possible — and usually what it costs.
- ⧉ spans the ladder
- The strata disagree about capability.
- overtreatment risk
- Real capability, a permanent price, and no way to say who needed it.
- futile treatment risk
- Real capability, a permanent price, and no way to say who will respond.
- harm without benefit
- A major permanent toll on an entity whose course nothing alters. Nobody designed this category; it fell out of toll × capability. It does not mean the treatment does nothing. COPD is the case that proves the point — no drug slows the loss of lung function, and bronchodilators substantially relieve breathlessness, which is the whole of what the disease costs a person. This register measures benefit only as course alteration and has no axis for symptom relief; the flag name is older than that realisation and is kept because queries use it.
Where the numbers come from