dckcandClaude Opus 5.5
d59efbcd16
Lessons from IBISing a2030.md's "Good Fences Make Good Agents":
arguments got pinned to the wrong position, a ruling-out comment was
really a con, and several issues were already answered by the design
text. Numbering made terse replies ("2: ...") unambiguous, and one big
fenced block outgrew a screen.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
122 lines
5.1 KiB
Markdown
122 lines
5.1 KiB
Markdown
---
|
|
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.
|
|
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
|
|
```
|