From d59efbcd168dc9a36447d202cc35d8b556c8261f Mon Sep 17 00:00:00 2001 From: Dan Connolly Date: Thu, 8 Oct 2026 21:52:39 -0500 Subject: [PATCH] feat(ibis-design): add argument placement, numbering, and layout guidance 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) --- ibis-design/SKILL.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/ibis-design/SKILL.md b/ibis-design/SKILL.md index 1683d80..449d012 100644 --- a/ibis-design/SKILL.md +++ b/ibis-design/SKILL.md @@ -54,6 +54,23 @@ leading symbol on each item says what kind of element it is. 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 @@ -62,6 +79,12 @@ 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 ```