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.
7. Attach each argument to the position it bears on. If it applies equally to the siblings, it belongs higher up, or the issue is several choices (rule 6). A comment that rules a position out is a con, and the position is rejected (:-).
8. Check the source before raising an issue. If the design text already answers it, record the issue as resolved and cite that text as the pro.
9. Past three levels of nesting, split out a sub-issue.

numbering

Number elements so replies can refer to them ("2: …"): issues 1, 2; positions under them 1a, 1b; anything below that 1a-i, 1a-ii, then 1a-i-a. The number follows the symbol: ?! 2. …, :+ 2c. …. Renumbering breaks references made in chat or other docs, so append rather than renumber once people are citing numbers. Show dependencies between issues with "(see 5)".

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.

Past a screenful, give each top-level issue its own heading (### ? 3. What is the fence?) with its elements in a fenced block below. Headings show up in the editor outline and give each issue a link target. Links don't render inside a fence, so put sources after the block and refer to them from the line they support.

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