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 ```