---
name: ibis-design
description: >-
  IBIS / issue-based information system — use when writing or reviewing a design discussion, decision record, or outline of issues, positions, and pro/con arguments; when someone marks lines with `?`, `?!`, `?~`, `:`, `:+`, `:-`, `:~+`, `+`, `-`, `!`, `.`; when asked to "IBIS this", lay out options for a decision, record a fallback, or capture why a choice was made. Source: dckc/vattr97 wiki IBIS page.
---

# IBIS design discussions

[IBIS page on the vattr97 wiki](https://github.com/dckc/vattr97/wiki/IBIS),
condensed to working rules. See also
[Issue-based information system on Wikipedia](https://en.wikipedia.org/wiki/Issue-based_information_system).

IBIS develops solutions to issues asynchronously and keeps the
reasoning around so the resolution can evolve. It's an outline; a
leading symbol on each item says what kind of element it is.

## symbols

| Symbol | Meaning |
| :---: | :--- |
| `?` | an issue to be considered |
| `?!` | a resolved issue |
| `?~` | tentatively resolved, or still open but with a fallback position |
| `:` | a position on an issue (positions on one issue may overlap) |
| `:+` | an accepted position |
| `:-` | a rejected position |
| `:~+` | tentatively accepted, or the fallback position for the issue |
| `+` | pro: an argument for a position |
| `-` | con: an argument against a position |
| `!` | a to-do on an element (optionally with initials: `!jf`) |
| `.` | a comment on an element |

## rules

1. **Phrase issues to admit overlapping positions**, as complete
   sentences — not yes/no. "? What tools should we provide for
   enterprise developers?", not "? Should we support VSCode?"
2. **Positions are complete sentences** proposing a full or partial
   solution. They may overlap or conflict, and needn't capture every
   ramification — refine them with sub-positions.
3. **Nesting:**
   - A sub-issue discusses a portion of its outer issue; its positions
     nest under it.
   - A sub-position refines its parent *assuming the parent is
     accepted*; its arguments nest under it.
   - Arguments are always pro or con with respect to their containing
     issue, so a `+` under a `-` is typically a mitigation ("here's why
     that con isn't so bad").
4. **An issue is resolved only when some position is accepted.** Not
   every position needs an accept/reject verdict.
5. **Use fallbacks (`?~`, `:~+`) to agree on a minimum bar** while
   leaving the issue open. The first fallback is often the status quo.
   Being the fallback must not preclude considering other options —
   that's what keeps fallbacks easy to agree on.
6. **When one issue is really several choices, say so** with a `.`
   comment and split it into sibling `?` sub-issues.

## writing it in markdown

A leading `-` or `.` collides with list syntax and editor
auto-bulleting. Put each symbol after the list marker, escaping where
needed (`- \- con`, `- \+ pro`), or use a fenced block with indentation
as in the example below.

## example

```
? How should we test our software?
  : use a test runner of some form
  : build a QA department
  :~+ use tape
    + it's what we currently use
    + it's very simple
    + it works in numerous environments
      - it's not very expressive
    - it doesn't have code coverage
  : use Jest
    + lots of people like it
    - guess-my-syntax DSL for expressing assertions
      + you can separate the assertion choice from the framework
    + can do integration and unit tests very well
      !jf can it do them better than tape?
  : roll our own test runner
    : make them importable ESM
      . then we can run them in XS
      + could be simpler than tape
      - requires implementation and maintenance
  :+ use test262
    + required for JS standards testing
      - clunky for other uses
  . there are actually three separate choices: test runner, test environment, and assertion library
  ? What assertion library should we use?
  ? What test runner should we use?
  ? What test environments should we support?
    : SES
    : NodeJS
    : in-browser
```