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.
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.
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.
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.
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.
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.
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
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.
Scope often changes late in the sprint.
Proposed. Captured but not yet agreed. Your own statements start here too.
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.
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.
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.
- 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.
- 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.
- 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.
- 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
| 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 memoryOne YAML file holds the participants, statements, connections, standing and open work.
- History you can trustWhenever accepted reasoning changes, the helper saves a numbered snapshot that is never edited afterwards.
- Views from the fileDiagrams are generated from the saved reasoning, one standing at a time, with joint causes shown as AND.
- Works where you doDiagrams render in apps that support them and fall back to readable text where they don’t.
reason-commons.yaml · excerpt from the example sessionschema_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.
1The 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.
2You 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.
3The 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 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.
- 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.
- Unzip so the folder sits at
~/.claude/skills/reason-commons/. To share it with a project, use.claude/skills/inside the repository instead. - Start Claude Code and describe your problem, or type
/reason-commons. - For diagrams and history snapshots, install PyYAML:
pip install pyyaml.
- Unzip so the folder sits at
~/.agents/skills/reason-commons/. To share it with a repository, use.agents/skills/inside it instead. - Start Codex in the CLI, the IDE extension or the ChatGPT desktop app, and describe your problem. Restart Codex if the skill doesn’t appear.
- For diagrams and history snapshots, install PyYAML:
pip install pyyaml.
Your first ten minutes
- 01It 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.
- 02Within a few answers you’ll see your first piece of reasoning, and you can accept it for now or revise it.
- 03It names one next step each turn and says why. You can always go a different way.
- 04Your reasoning is saved to
reason-commons.yaml, with snapshots in a.reason-commonsfolder 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?
Each turn is a short exchange, and you can stop whenever you like. If you ask what to do, it recommends one next step with the reasoning behind it. The extra minutes go into reasoning you’ll understand, agree on and keep.
Can I use it on my own?
Yes. One participant is enough. In a group, say who’s speaking and each contribution is attributed to that person. Being listed as a participant never counts as agreeing.
Where does my reasoning go?
Into a plain-text file in your workspace, named reason-commons.yaml unless you choose another name, with snapshots and diagrams in a folder beside it. The skill has no server of its own. Your conversation runs in the AI assistant you already use, under that assistant’s terms.
What do I need to run it?
An assistant that supports skills: Claude with code execution turned on, Claude Code, or Codex. Python with PyYAML enables the diagrams and history snapshots.
What if it gets something wrong?
Correct it in plain words. Everything stays proposed until someone accepts it, and you can reword a statement, fix who said what or dispute a connection at any point.
Does it work for a whole team?
Yes, in one session with one person at the keyboard and the other participants named. Several people editing the same reasoning at once isn’t supported yet.
What does it cost?
The skill is a download with no separate account. Using it counts toward your plan with whichever assistant you run it in.
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.