Captured document text and technical evidence
Skip to content
Reason Commons
See a session
Use cases
What’s different
Questions
Try it
Guided reasoning, in plain words
Untangle the problem you keep coming back to.
Reason Commons is an AI facilitator for recurring problems, stuck decisions and plans you aren’t sure about. It asks one useful question at a time, maps your reasoning as you answer, and keeps a record of what you’ve agreed, what’s disputed and what still needs testing.
Try it on your problem
→
Watch a session unfold
Runs inside Claude or Codex
No method to learn first
Works alone or with a team
EXAMPLE SESSION
scripted
Focus: why releases slip · Driver: Maya · Other participants: Jon
MAYA
Our releases keep slipping. Usually by about two weeks, sometimes more.
P
PROPOSED
PROBLEM
Maya
Releases usually slip by about two weeks, sometimes more.
Recorded as proposed, with her qualifiers kept
REASON COMMONS
NEXT: Think of the last release that slipped. What was the first thing that didn’t happen when you expected it to?
WHY: One real case shows where the delay starts, before anyone guesses at causes.
One question, with the reason for asking it
The pattern
You’ve been here before.
Retro notes · third time this quarter
The fix that didn’t stick
The same issue is back in the retro. Every fix made sense when you made it. None of them reached whatever keeps causing it.
Decision log · open for six weeks
The argument on repeat
Two people you trust keep making the same points. Each is right about something. Six weeks on, the decision still isn’t made.
Plan review · approved
The plan everyone nodded at
It sounded convincing in the meeting. Nobody traced how the first step leads to the result, or what it might break along the way.
Six months later
The reason nobody kept
Someone asks why you chose this. The people who knew have moved on, and the thread that explained it is buried somewhere.
These have the same root. The reasoning underneath stays in people’s heads.
What leads to what, what each side needs, what has to be true for the plan to work. Nobody lays it out, so nobody tests it. Nobody records it, so every discussion starts again from the beginning.
Why AI hasn’t fixed it
Answers are abundant. Reasoning isn’t.
Ask a general-purpose AI and you’ll get a confident, well-organised answer in seconds. It reads well. It’s also built from the model’s assumptions about situations like yours, its guesses sit next to your facts without a label, and nothing records which parts you actually accept. Next week you’re back with the same problem and a slightly different answer.
A TYPICAL GENERIC ANSWER · ILLUSTRATIVE
Release delays often come from scope creep, testing bottlenecks or optimistic estimates. Common fixes:
Freeze scope earlier in each cycle
Automate regression testing
Ship unfinished work behind feature flags
Track cycle time to find the bottleneck
Want a rollout plan for any of these?
Sensible fixes, drawn from teams in general. Nothing here checks what is actually happening on yours, or keeps track of what you agree with.
A REASON COMMONS TURN · EXAMPLE
P
PROPOSED
PROBLEM
You
Releases usually slip by about two weeks, sometimes more.
NEXT: Has a recent release shipped on time? If so, what was different about it?
WHY: A release that didn’t slip is the quickest way to test any explanation you already have.
One question about your situation. The answer goes into a map you can test, agree on and keep.
Why this exists
Clear thinking shouldn’t be a privilege.
The methods behind Reason Commons come from Eli Goldratt’s Theory of Constraints and H. William Dettmer’s Logical Thinking Process. Since the 1990s they’ve mostly been taught in workshops and consultancies, to people with the time and budget to learn them.
Reason Commons puts their questions into an ordinary conversation, in plain words. It keeps a record of who said what, and of what each person has accepted for now. It doesn’t claim to have the answers. It helps you find your own, test them, and change your mind when the evidence says so.
Today it’s a skill you add to Claude or Codex.
Good reasoning belongs to everyone.
A different way to work
Make the reasoning itself the thing you work on.
Reason Commons turns a conversation into reasoning you can see, test and keep. You talk the way you normally would. The structure builds up underneath.
Lay it out
What you say becomes clear, single statements joined by the connections you describe. Words like “usually” and “might” stay in.
Test it
Connections get examined one question at a time. Why would this lead to that? What else has to be true? Is it necessary, or only helpful?
Agree on it out loud
Everything starts as proposed, your own claims included. Nothing becomes accepted until someone says so, and objections stay on the record with their author.
Keep it
The reasoning is saved to a plain file you own, with a numbered snapshot whenever accepted reasoning changes. Pick it up next week where you stopped.
How agreement works
Everything starts in pencil.
Each statement and connection carries a standing, shown by its border as well as its label, so you can always tell what’s settled for now and what isn’t.
P
PROPOSED · CAUSE
Jon
Scope often changes late in the sprint.
Proposed. Captured but not yet agreed. Your own statements start here too.
A
ACCEPTED · PROBLEM
Maya
Releases usually slip by about two weeks, sometimes more.
Accepted for now by Maya and Jon
Accepted for now. Someone said they’re willing to build on it. It isn’t a claim of proof, and it can be reopened.
D
DISPUTED · CAUSE
Maya
Late QA is what makes releases slip.
Objection (Jon): March shipped on time even though QA started late.
Disputed. Someone objected. The objection and its author stay attached until it’s resolved.
See it work
Watch a session take shape.
Step through two short sessions. Each turn captures what was said, updates the map and asks one question.
Releases keep slipping
2 people
Hire now or wait?
1 person
SCRIPTED EXAMPLE
MAYA
Our releases keep slipping. Usually by about two weeks, sometimes more.
REASON COMMONS
SAVED: One problem, proposed, with your qualifiers kept.
NEXT: Think of the last release that slipped. What was the first thing that didn’t happen when you expected it to?
WHY: One real case shows where the delay starts, before anyone guesses at causes.
Focus: why releases slip · Driver: Maya · Other participants: Jon
REASONING MAP · STEP 1
P
1 proposed
A
0 accepted for now
D
0 disputed
P
PROPOSED:
PROBLEM
Maya
NEW
Releases usually slip by about two weeks, sometimes more.
Notice:
The statement keeps “usually” and “sometimes more”, and it starts as proposed even though Maya said it herself.
←
Back
Next step
→
These sessions are scripted to show how the skill behaves. The map shows what the session file records, including who offered each item. The skill’s own diagrams in chat focus on structure and standing. The live preview further down runs on your own Claude account.
How a session works
Four moves, at your pace.
Bring what you already know
A symptom, a stalemate, a plan or a goal. There’s no template to fill in. The structure is chosen from what you say.
Answer one question at a time
Each turn ends with one focused question and the reason for asking it. Take a different direction whenever you like.
Watch it firm up
Your answers become statements and connections, proposed until you accept them. Untested links and open objections go on a short list of work.
Leave with something to act on
What you agree on, what’s disputed and the next test worth running, saved so you can pick it up again.
Where it helps
Bring it the thing you’re stuck on.
Four common starting points. Copy a prompt to use with the skill, or adapt it to your situation.
A recurring problem
Why does this keep happening?
START WITH
Our releases keep slipping, usually by about two weeks. Help me work out why before we change anything else.
Copy prompt
IT MIGHT OPEN WITH
Think of the last time it happened. What was the first thing that didn’t go as expected?
YOU LEAVE WITH
The causes you’ve tested, the ones you accept for now, and the check that would change your mind.
A stuck disagreement
Why do we keep having this argument?
START WITH
My co-founder wants to hire now and I want to wait until revenue covers it. We’ve argued for a month. Help me see what each of us actually needs.
Copy prompt
IT MIGHT OPEN WITH
What do you think your co-founder is trying to protect by hiring now?
YOU LEAVE WITH
Both positions, the need behind each, the assumption that makes them clash, and an option worth testing.
A change you’re about to make
Will this plan actually work?
START WITH
We’re moving customer support to tickets only. Help me check whether it will really cut response times, and what it could make worse.
Copy prompt
IT MIGHT OPEN WITH
If it works exactly as you hope, what would a customer notice first?
YOU LEAVE WITH
How the change should produce the result, what else has to hold, and the side effects to guard against.
A goal that’s still fuzzy
What does good look like here?
START WITH
I want our onboarding to be better, but I can’t say what better means. Help me pin down the goal and what it depends on.
Copy prompt
IT MIGHT OPEN WITH
Picture a new customer’s first week once onboarding works the way you want. What’s different for them?
YOU LEAVE WITH
A clear goal, the few conditions it depends on, and a check on each one that asks whether you could reach the goal without it.
Opening questions are examples of how the skill tends to start. Your session follows what you actually say.
What’s different
What it does that a plain chat doesn’t.
The skill follows facilitation rules written into it. These are the ones you’ll notice first.
It asks before it assumes
If your reasoning depends on something that’s missing, it helps you establish it instead of filling the gap itself.
Your qualifiers survive
“Sometimes” stays “sometimes”. A hunch isn’t quietly rounded up into a fact when it’s written down.
Its own ideas are labelled
When the AI suggests a cause or a connection, it says so, and the file records it as the AI’s, separate from what people said.
Silence isn’t agreement
Moving on, viewing the map or saying nothing never counts as acceptance. Only an explicit yes does.
Objections stay attached
A challenged claim is marked disputed, with the objection and who raised it, until you resolve it.
It finishes before it widens
Once there’s enough material, it works through untested links and open questions before asking you for more.
How it compares with what you’d use today
How it compares with what you’d use today
QUESTION
ASKING A GENERAL AI WHITEBOARD OR DIAGRAM TOOL MEETING AND NOTES REASON COMMONS
You come away with An answer to evaluate A diagram Decisions and notes Your reasoning, laid out and tested
Whose thinking it is The model’s, blended with yours The group’s, as drawn The group’s, as remembered Yours, with the AI’s suggestions recorded as its own
What counts as agreed Not tracked Not tracked Whatever the notes say, if someone writes them Explicit: proposed, accepted for now or disputed
How claims get tested When you ask it to As the group discusses When someone pushes back Built into each session, one connection at a time
What’s left a week later A chat history A picture, without the reasons Notes, if someone took them A file with history and who said what, kept wherever you keep the file
Under the hood
A careful method you don’t have to learn first.
Reason Commons draws on the Logical Thinking Process, a set of reasoning structures from the Theory of Constraints for mapping causes, resolving conflicts, checking proposed changes, clearing obstacles and sequencing action. The structures are thorough, and they usually take training to use well. You don’t need to know them to start. The skill picks the structure from what you bring, and its diagrams name each structure when you want to look closer.
Plain-text memory
One YAML file holds the participants, statements, connections, standing and open work.
History you can trust
Whenever accepted reasoning changes, the helper saves a numbered snapshot that is never edited afterwards.
Views from the file
Diagrams are generated from the saved reasoning, one standing at a time, with joint causes shown as AND.
Works where you do
Diagrams render in apps that support them and fall back to readable text where they don’t.
reason-commons.yaml · excerpt from the example session
schema_version: 1
links:
- id: l3
from: [c1, c2] # two causes acting together
to: e1
relation: contributes_to
status: accepted
accepted_by: [maya, jon]
contributions:
- {by: assistant, attribution: assistant, mode: text}
- id: l1
from: [c1]
to: e1
relation: contributes_to
status: disputed
contributions:
- {by: maya, attribution: explicit, mode: text}
challenges:
- {text: Late QA on its own didn't cause a slip in March., by: jon}
For teams that build with AI agents
Every change traced to the reasoning it serves.
When an AI agent edits your code, the reason for each change is easy to lose. Inside a repository, the skill has the agent show a change proposal before it edits anything: the reasoning the change serves, the files it will touch and how the result will be checked. The agent waits for your typed acceptance, which is recorded with your exact words, the scope and the time. A pull-request check then confirms that every changed file and reasoning update is covered by an acceptance on record.
EXAMPLE, ABBREVIATED
The real proposal also includes a diagram of the tree updates.
1
The agent proposes
Type: Change proposal
Proposal: release-scope-freeze · revision 1
Change: Add a scope-freeze date to the release checklist.
Files: docs/release-checklist.md, reason-commons.yaml
Reasoning served: Future Reality · Injection · Proposed · f1: Freeze scope two weeks before QA on the next release. It addresses e1, the release slips.
Tree updates (proposed): Add Transition · Action · Proposed · t1: Add a scope-freeze date to the release checklist. Implements f1.
Validation: The next release records a freeze date, and its ship date is compared with the prediction in f2. One release can support the explanation but can’t prove it.
Status: Awaiting your typed acceptance before implementation, because changes to project files need a recorded approval. Reply to accept this version, or say what to change.
“Injection” is the method’s word for a change you propose. A transition action is one step that puts it in place.
2
You accept, in your own words
Maya: Yes, accept release-scope-freeze
revision 1.
change_acceptances:
- proposal_ref: release-scope-freeze
proposal_revision: 1
by: maya
recorded_at: '2026-10-18T09:12:00Z'
timezone: Europe/Berlin
mode: text
source: conversation
source_text: Yes, accept
release-scope-freeze revision 1.
scope: Add a scope-freeze date to
the release checklist, and the
proposed action t1.
node_ids: [t1]
link_ids: []
approved_paths:
[docs/release-checklist.md,
reason-commons.yaml]
The receipt keeps who accepted, what they typed, the scope, the files and when it was recorded. Approving the work doesn’t count as agreeing with the reasoning.
3
The pull request is checked
$ check_pr_trees.py reason-commons.yaml --base origin/main --body-file pr.md
Tree check passed: serves 1 existing item(s); 1 tree update(s) match the YAML; recorded acceptances cover 2 changed file(s).
The check fails if a changed file or reasoning update isn’t covered by an acceptance on record, or if an earlier receipt was altered. It verifies coverage. It can’t prove who typed an acceptance or that the code does what was approved, so people still review the work.
Works in Claude Code and Codex. Comes with a pull-request template and a GitHub Actions workflow you can add to your repository once you point its paths at your copy of the skill.
Get started
Try it on your problem.
Start a short live session right here, or add the full skill to the assistant you already use.
LIVE PREVIEW
Runs on your own Claude account. Nothing is saved.
The live preview isn’t available here.
It needs Claude, signed in, and this view can’t reach it.
You can still step through the scripted sessions above, or get the skill below and paste your problem into Claude.
Watch the scripted session
The full skill
Keep going, and keep the reasoning.
The full skill saves your reasoning to a file, keeps its history and works with a whole team.
Download the skill
.zip · 72 KB
Claude
Claude Code
Codex
Download the skill.
In Claude, open Customize, then Skills, and add the .zip file.
Check that code execution is turned on. The skill uses it to save your reasoning.
Start a new chat and describe your problem, or paste one of the prompts above.
Your first ten minutes
01
It asks what’s going on, in your words. If you ask what to do, it recommends one next step and shows the reasoning behind it.
02
Within a few answers you’ll see your first piece of reasoning, and you can accept it for now or revise it.
03
It names one next step each turn and says why. You can always go a different way.
04
Your reasoning is saved to reason-commons.yaml, with snapshots in a .reason-commons folder beside it. In Claude Code or Codex both stay in your project. In the Claude app, ask Claude to zip them before you finish and attach the zip next time.
Where this could go
A commons for reasoning.
Today Reason Commons is a skill you add to the AI assistant you already use. The idea underneath is bigger. Reasoning can become a shared resource that people build together, test in the open and keep, so decisions stay connected to the thinking behind them.
Available today
IN THE SKILL
Guided sessions for one person or a group, in Claude and Codex
Proposed, accepted-for-now and disputed standing, with who said what
A saved reasoning file with numbered history and generated diagrams
Change proposals, recorded approvals and pull-request checks for code
Not built yet
POSSIBLE NEXT STEPS
Shared spaces where a team adds to the same reasoning at the same time
A searchable record of why past decisions were made
Automatic reminders to compare a plan’s predictions with what actually happened
Open commons where communities reason through contested questions in public
The “Not built yet” column describes directions the approach points toward. None of it is available today.
Questions
Before you try it.
Do I need to know the method?
No. Describe the situation in your own words and the skill chooses the structure. Its diagrams use the method’s names, so you’ll pick them up if you want to.
Isn’t this slower than just asking for an answer?
Can I use it on my own?
Where does my reasoning go?
What do I need to run it?
What if it gets something wrong?
Does it work for a whole team?
What does it cost?
Bring the problem you keep coming back to.
Answer one question at a time and you’ll see it laid out in your own words, with the next thing worth testing.
Try it on your problem
→
Download the skill
Reason Commons
Good reasoning belongs to everyone.
A skill for reasoning things through, alone or together. The example sessions on this page are scripted to show how the skill behaves. The live preview runs on the viewer’s own Claude account and saves nothing.{
"layout": {
"width": 1440,
"scroll_width": 1440,
"height": 14645,
"overflowing": []
},
"errors": [],
"entry_sha256": "df0ecd31046f5db32df56645f27bc00e7edbfc33afd676af2ce70b5b57bc8f56",
"source_sha256": "df0ecd31046f5db32df56645f27bc00e7edbfc33afd676af2ce70b5b57bc8f56",
"images": [
{
"ref": "image-0",
"file": "untangle-the-problem--desktop-00.png",
"sha256": "690e49cead322556522b266a09bfc2feb69dd27fe47c4699c0dd284d9e71f6e3",
"y": 0
},
{
"ref": "image-6",
"file": "untangle-the-problem--desktop-06.png",
"sha256": "f4cb97b5add48d9f2fc73fcefbdb2eece6d1fa115948d13fab267bc4d1dd4c02",
"y": 4920
},
{
"ref": "image-11",
"file": "untangle-the-problem--desktop-11.png",
"sha256": "99d551b711de97db835b19ef7698ac57c850a775bd48b47ee0ec0aa84f23b3fa",
"y": 9020
},
{
"ref": "image-17",
"file": "untangle-the-problem--desktop-17.png",
"sha256": "7125d913c018686285f5ded5e3d73f83a0e14ed7e09ddfc4ec125fcaf0602940",
"y": 13745
}
]
}