Form
IBIS diagram as image or digital map with issues, positions, and arguments plus a Markdown document with hierarchical structure, Decision Rationale, open sub-issues, and owners.
RunsheetKnowledge Modeling
IBIS
ComplexityMedium
Time1-3 h
Participants2-8
FormatWorkshop + async
MaturityCanonical
01
Preparation
What needs to be ready before start
Materials
Whiteboard or Miro board with three colors of notation (issue as question, position as statement, pro and contra argument symbols); symbols for pro (+) and contra (-); markers; timer; shared definition of IBIS notation.
People / roles
A facilitator with IBIS experience; two to eight participants with domain and architecture knowledge; a scribe who maintains the map and consolidates digitally afterwards.
Pre-read
Central issue (question) as starting point; existing design docs or architecture decisions; list of existing discussion states; definition of what counts as argument (qualitative, quantitative).
Time needed
1-3 h
Setup
Display the issue at the top as a question. Show symbols for position and argument type. State the rule: each position answers one issue, every argument references one position.
02
Core question
The one question this method answers
Which positions answer the central issue, and which arguments support or challenge each position?
03
Flow
Marker: Phase
| Step | Duration | Action | Hint |
|---|---|---|---|
1Phase 1: Frame the issue | 10-15 min | Formulate the main question as an open issue ("How should we solve X?"). Split broad scope into sub-issues. Place the top issue at the top of the board. | Issues are open questions, not judgments. "Should we do X" is a judgment and should be reframed as "How can we achieve X given Y and Z?" |
2Phase 2: Gather positions | 20-30 min | Collect possible answers to the issue as positions (at least three). Use one clear sentence per position with a concrete answer. | If only one position is named, the discussion is not open. The facilitator generates at least one counter-position with a devil's advocate role. |
3Phase 3: Assign arguments | 30-45 min | Collect pro and contra arguments for each position. Arguments can be data, experience, or constraints. Add arrows from argument to position and make pro/contra symbols visible. | Some arguments apply to multiple positions. Add a separate arrow per relationship to avoid illegible maps. |
4Phase 4: Check relationships | 20-30 min | Review the map together. Mark weak arguments. Note sub-issues that arise as new issues ("issue knot"). | IBIS maps often produce issue knots that belong in separate sub-maps. Do not force all content into one map. |
5Phase 5: Make a decision or keep open questions | 15-20 min | Mark position(s) driving decisions. Add rationale in the Decision Log. Add owner and date for open sub-issues. | IBIS is primarily documentation, not a decision engine. If no position dominates, pass decision to the decider with the map as an attachment. |
04
Artifact
What comes out at the end
Versioning / ownership
One map per issue with date. For new information or overturned decisions, create a follow-up map as v2; keep old positions marked as "rejected" with rationale.
Tool alternatives
- Compendium or DesignVUE for classic IBIS tools
- Miro with IBIS template
- Markdown with indented list in ADR repo
- draw.io with directed graph
ibis-working-template.md
Compact working template for IBIS with context, input, output artifacts, and next step.
IBIS Canvas
Context
What is this method used for?
Core question
Which question should be answered at the end?
Input
Which data, observations, or materials are available?
Working area
- Area 1:
- Area 2:
- Area 3:
- Relationships / patterns:
Output artifacts
- Issue Map:
- Positions:
- Argument Notes:
Open questions
- ...
Next step
Owner, date, success signal.
05
Example output
Concrete filled scenario, fictional example
ibis-beispiel.md
Concrete filled scenario, fictional example
IBIS — Authentication strategy for a new app (19.05.2026)
Issue: How do we integrate authentication for a new mobile app given existing web OAuth?
Positions:
- P1: Reuse OAuth2 with PKCE.
- P2: Build a custom mobile SDK with token-refresh flow.
- P3: Use a third-party identity provider (for example Auth0, Okta).
Arguments:
- P1 (+): Existing infrastructure is reusable (evidence: production since 2024).
- P1 (-): PKCE implementation is complex on iOS (experience anecdote, spike planned).
- P2 (+): Full control over UX (argument: design requirements from user interviews).
- P2 (-): High internal effort (estimate 6 PT).
- P3 (+): SLA and compliance features (evidence: provider list including ISO 27001).
- P3 (-): recurring cost after 10k users.
Issue knot (sub-issue): How do we migrate existing web tokens to mobile tokens? Owner: @ben, spike by 30.05.
Decision: P1 with spike for PKCE-iOS. Decider: @julia. Rationale: reuse wins over greenfield; third-party option is deferred due to cost and data residency.
06
Pitfalls
Recognize symptoms and steer against them
Trap
Issues are judgments instead of questions
Symptom
The issue is framed as "Should we do X" and the map drifts into a pro/con list without position diversity.
What to do
Frame issues as open "how" questions. Pro-con lists are argument mapping, not IBIS.
Trap
Positions are mixed
Symptom
One position contains multiple answer options in one sticky.
What to do
Use one clear sentence per position with one concrete answer. If hybrids are relevant, create a dedicated position for them.
Trap
Arguments branch without control
Symptom
Arguments evolve into sub- and sub-sub-arguments, making the map unreadable.
What to do
Avoid more than two levels under one position. Branches should become sub-issues and be handled in separate maps.
Trap
No decision rationale
Symptom
The map is detailed but lacks a final decision or rationale.
What to do
Phase 5 is mandatory. Add a short rationale for each decision with top arguments. If no decision is possible, add open sub-issues with owners.
Trap
Map becomes outdated quickly
Symptom
A position is implemented but the map still shows old arguments and sub-issues.
What to do
Update the map with every architecture or design change, or create a new version. Otherwise the map becomes historical misinformation.
07
Stop criteria
Done signals checkable in under a minute
The issue cannot be framed as an open question within 15 min.
Only one position is represented and no real discussion can occur.
No person with subject knowledge is present, so arguments remain speculative.
Workshop shorter than 45 min, making five phases impossible.
Discussion is primarily emotional or conflict-heavy, IBIS notation is not useful.
No decision authority in the room or decision is not transferred into a Decision Log.
Finished the runsheet?
Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.