mad-skills/ibis-design/SKILL.md

name, description

name

description

ibis-design

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, condensed to working rules. See also Issue-based information system on Wikipedia.

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