one agent's answer sounds reasonable, and you have no way to know it is right.

what it does

you have a result and you do not know the cause. a video spread unexpectedly, a product did not sell, an email went unopened. four or five explanations are floating in your head, they all sound sensible, and you cannot tell them apart.

ask one agent "why do you think this happened" and it writes an answer that looks reasonable. looking reasonable and being right are not the same thing. this system makes that answer face a referee.

there are five roles. four defend a theory: the marketer ties the result to packaging, the editor to craft, the skeptic to an external cause, the psychologist to viewer intent. the fifth role is the mathematician and it defends nothing. its only job is testing every theory against the numbers in the data folder.

how you use it

you do not need to know a terminal. you pull the system from github and the rest happens in chat.

the easiest way to pull it: open claude code or codex, give it github.com/muhammedsevimli/systems/tree/main/agent-team and say "install this into this folder". if you know the command line, npx degit gets it in one line, and if you want neither, github hands you a zip.

then open claude code or codex in that folder and describe your result: "the short video i posted last week got 42,000 views in a day and the previous episodes were stalling at 5,000, i want to know why" is enough.

the tool takes it from there. it sharpens the question, then writes out which numbers it needs, one by one, and asks you for them. you type the numbers, paste a screenshot, or hand over an exported report. the tool writes the data file itself and shows it to you so it knows it read everything correctly. you never touch a folder, a prompt file or an output file by hand.

how it works

1. the numbers are collected into one data file. no role may use a figure that is not in it.
2. five agents start at the same time. each runs in its own context and cannot see inside the others.
3. in round one each role writes its theory and cites two or three numbers from the data. the mathematician marks every theory "consistent with the data" or "contradicted by the data" and shows the arithmetic.
4. in round two each role reads what the others wrote. if convinced it writes OUT and says in one sentence why it withdrew. if not, it writes STANDING and brings counter-evidence.
5. the theory left standing lands in a one-page report and gets summarized in chat.

the mathematician runs with read-only tools and writes no files. keeping the referee's hands off the output of the debate is deliberate.

if the data is not enough to test a theory the referee writes "cannot be separated" instead of turning that gap into weak evidence. this is the most important behavior in the system.

proof that it works

i ran it on a real question the day it was built. one episode of a short video series took 85,064 views a day after posting. the previous episode in the same series was built on the same pattern and stayed at 5,800. the question: why did this one spread.

five roles ran, two rounds turned, three theories were cut.

the editor was cut. the edit and audio measurements of the two episodes were nearly identical. music to speech separation was 22.0 lu in both, the mix was -16.0 and -16.3 lufs, and there were zero full black frames. a variable that stayed constant cannot produce a 14.7x gap.

the skeptic was cut. the non-follower share was 95.9 percent. follower unique viewers came to 67,051 x 0.041 = 2,749. for that group to carry 67,051 unique viewers each one would have had to bring 24 viewers, and total shares were 1,150.

the marketer withdrew on its own. the referee did not cut this theory, it said "cannot be separated with this data": another episode in the series had taken 102,000 without that opening format. the agent saw this and pulled its theory back.

the psychologist stood. saves 3,721, which is 3.38x the likes (1,100). comments 2,927, which is 2.66x the likes. of 8,919 total engagements, 6,648 or 74.5 percent were saves and comments. likes measure feeling, saves and comments measure intent.

the run took five agents, two rounds, about four minutes and roughly 570k tokens. five agents running at once costs roughly five times what one agent costs. i would start with three: two theories plus the referee.

i wrote down what was not tested too: no scenario came up where two theories both stood, no agent tried to invent a number so the correction gate in round one never fired, and a mixed setup with different model tiers was not tried.

the full code is open: github.com/muhammedsevimli/systems

delivery

leave your email above. you get the step-by-step setup doc here and in your inbox. the five role files and four ready scenarios (a video that spread, a product that did not sell, an email that was not opened, an ad that was not clicked) are all in it. if you get stuck setting it up, write me.