From 20072d10809bd512f0810f9976d865d943d5a48f Mon Sep 17 00:00:00 2001
From: Dan Connolly <dckc@madmode.com>
Date: Thu, 8 Oct 2026 18:36:03 -0500
Subject: [PATCH] feat(ibis-design): add skill

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 ibis-design/SKILL.md | 98 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 ibis-design/SKILL.md

diff --git a/ibis-design/SKILL.md b/ibis-design/SKILL.md
new file mode 100644
index 0000000..1683d80
--- /dev/null
+++ b/ibis-design/SKILL.md
@@ -0,0 +1,98 @@
+---
+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
+```