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) <noreply@anthropic.com>
This commit is contained in:
dckcandClaude Opus 5.5 committed 2026-10-08 21:52:39 -05:00
1 parent 1ecf625427
commit d59efbcd16
1 file changed
+23
+23
View File
@@ -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
```