docs / 00-how-it-works.md
How it works
An analyst and a set of AI agents write a political economy analysis together. Every statement of fact in it points back to the words in a source that say it.
This is the design. A first version runs: sign-in, the registry, search, document fetching, and a workspace where one agent searches, reads and makes claims beside the analyst, who can promote a claim to the registry. The check and agents working in parallel are not built yet.
The whole thing
- An analyst sets the question: a country, a problem, and who the analysis is for.
- The registry says where to look. The agents fetch documents, and a model quotes the pages that bear on the question. Each quote is checked against the stored text.
- Each finding becomes a claim: a sentence, plus the words in a source that carry it.
- The agents and the analyst write the draft together. It cites claims, not links.
- A check reads the draft back against its claims and flags any fact with nothing behind it.
What the analysis learned about its sources goes back into the registry for the next one. A route that worked, a PDF that turned out to be a scan, a place that had nothing.
Four ideas
| Claim | A sentence plus the words in a source that carry it. Everything else is built on claims | Claims |
| Registry | The shared map of where to look. It outlives each analysis and gets better with each one | The registry |
| Workspace | One analysis. Chat on one side, the document and its evidence on the other | One analysis |
| The check | The draft is read back against its claims. Unsupported facts are flagged where they sit | The check |
Who decides
| Who | What they do |
|---|---|
| Agents | Search, read, write claims, draft. They propose and never approve |
| Analyst | Steers the agents, rewrites anything, adds what only they know |
| Expert reviewer | Rejects a claim. The claim stays, with who rejected it and why |
| Curator | Approves changes to the registry. The change carries their name |
Every record says whether a person or an agent made it.
What it does not do
- It does not score confidence. A claim carries three plain labels instead — how sure.
- It does not average sources that disagree. It keeps both, side by side.
- It does not let the model write a link. Code turns a claim into an endnote.
- It does not replace interviews. When only an interview would answer, it says so and names who to ask.
The full design is under technical.