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:
1 parent
1ecf625427
commit
d59efbcd16
1 file changed
+23
@@ -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
|
||||
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user