style-guide.md
1 # Style Guide 2 3 > For Claude instances: This is mandatory. Violations should be self-corrected immediately. 4 5 --- 6 7 ## Configuration 8 9 ```yaml 10 # In repo root or .claude/style.yaml 11 style: 12 emojis: false # Set true to allow emojis 13 syntax: roam # roam | markdown | plain 14 ascii_diagrams: true # Box-drawing characters allowed 15 ``` 16 17 Default for this repo: `emojis: false` 18 19 --- 20 21 ## Core Principles 22 23 1. **Hierarchy is mandatory** - Flat structures lose a dimension of information 24 2. No emojis (configurable) - Default OFF for this instance 25 3. Roam/Obsidian syntax - Use `[[wikilinks]]` and `::` properties 26 4. Minimal markup - Prefer plain text over heavy formatting 27 5. Queryable structure - Use properties that can be filtered/searched 28 6. ASCII diagrams allowed - Box-drawing characters are not emojis 29 30 --- 31 32 ## Hierarchy (Non-Negotiable) 33 34 Flat lists lose information. Always express structure. 35 36 ### BEFORE Outputting Any List (Mandatory) 37 38 **STOP. Ask these questions BEFORE writing bullets:** 39 40 1. **How many items?** (If 3+, almost certainly has structure) 41 2. **Do any items belong together?** (Group by relationship) 42 3. **What are the categories?** (Name the parents) 43 4. **Parent-child or sibling?** (Determine nesting) 44 45 **Only THEN output.** 46 47 ``` 48 WRONG (skipped analysis): 49 "I need to output: handoff, branch, focus, current" 50 → Immediately write four flat bullets 51 52 RIGHT (did analysis): 53 "I need to output: handoff, branch, focus, current" 54 → "Do any belong together?" 55 → "handoff + branch = location info" 56 → "focus + current = content info" 57 → Write nested structure 58 ``` 59 60 **This is not optional.** Flat lists of 3+ items are a bug, not a style choice. 61 62 ### Why Hierarchy Matters 63 64 ``` 65 FLAT (loses signal): 66 - item one 67 - item two 68 - item three 69 - item four 70 71 HIERARCHICAL (preserves signal): 72 - category A 73 - item one 74 - item two 75 - category B 76 - item three 77 - item four 78 ``` 79 80 The hierarchical version tells you items one and two are related. Flat hides this. 81 82 ### Hierarchy Tools 83 84 | Tool | Use When | 85 |------|----------| 86 | Nested bullets | Items have parent-child relationships | 87 | Headers (##, ###) | Sections have different scopes | 88 | Indentation | Code/data has structural depth | 89 | Properties | Metadata should be queryable | 90 | Bold | Emphasizing keys in key-value pairs | 91 92 ### Footer Example 93 94 ``` 95 FLAT (bad): 96 handoff:: [[HANDOFF-2026-01-14]] 97 branch:: claude/research-graham-essay-rURpi 98 focus:: #promotion-pattern | #meta-infrastructure 99 current:: Research Paul Graham Essay 100 101 HIERARCHICAL (better, but still flat): 102 - **handoff**:: [[HANDOFF-2026-01-14]] 103 - **branch**:: claude/research-graham-essay-rURpi 104 - **focus**:: #promotion-pattern | #meta-infrastructure 105 - **current**:: Research Paul Graham Essay 106 107 TRULY HIERARCHICAL (best): 108 - **where** 109 - handoff:: [[HANDOFF-2026-01-14]] 110 - branch:: claude/research-graham-essay-rURpi 111 - **what** 112 - focus:: #promotion-pattern | #meta-infrastructure 113 - current:: Research Paul Graham Essay 114 ``` 115 116 The nested structure shows: handoff/branch are LOCATION, focus/current are CONTENT. Flat hides this relationship. 117 118 ### When to Add Hierarchy 119 120 Ask: "Is there structure here that flat representation hides?" 121 122 - Multiple items? Consider grouping 123 - Key-value pairs? Bold the keys 124 - Nested concepts? Use indentation 125 - Different scopes? Use headers 126 127 **Default assumption:** If it's flat, you're probably losing information. 128 129 --- 130 131 ## Syntax Standards 132 133 ### Properties (Roam Style) 134 135 Use `property:: value` format for metadata: 136 137 ``` 138 handoff:: [[HANDOFF-2026-01-14]] 139 branch:: claude/research-graham-essay-rURpi 140 focus:: [[Focus Detection]] | [[Meta-Infrastructure]] 141 status:: active 142 ``` 143 144 NOT: 145 ``` 146 **Handoff:** HANDOFF-2026-01-14 147 - Branch: claude/research-graham-essay-rURpi 148 ``` 149 150 ### Tags vs Wikilinks 151 152 Use `#tag` for short, thematic, categorical: 153 ``` 154 #pattern #pending #meta-infrastructure #protocol 155 ``` 156 157 Use `[[wikilink]]` for specific, concrete, document references: 158 ``` 159 [[HANDOFF-2026-01-14]] 160 [[Cognitive Cockpit Architecture]] 161 [[retention.py]] 162 ``` 163 164 Decision guide: 165 - Would you hashtag this on Twitter? Use `#tag` 166 - Is this a specific document or detailed concept? Use `[[link]]` 167 - Short theme/category (1-2 words) = `#tag` 168 - Concrete noun/title (2+ words) = `[[link]]` 169 170 Examples: 171 ``` 172 See [[handoff-protocol]] for details. # specific doc 173 This relates to #meta-infrastructure. # thematic category 174 The [[Cognitive DNA]] model uses #attention. # concrete + thematic 175 Status: #pending # categorical 176 ``` 177 178 ### Lists 179 180 Prefer `-` over `*` for bullets: 181 182 ``` 183 - Item one 184 - Item two 185 ``` 186 187 --- 188 189 ## Forbidden Patterns 190 191 ### Emojis 192 193 Never use emojis. This includes: 194 - Status indicators (use text: `status:: active`) 195 - Bullets (use `-`) 196 - Emphasis (use `**bold**` or caps sparingly) 197 198 **Lint rule:** Any Unicode character in emoji ranges is a violation. 199 200 ### Markdown Links for Internal References 201 202 Don't use `[text](path)` for internal references. Use `[[wikilinks]]`. 203 204 **Exception:** External URLs use standard markdown: `[text](https://...)` 205 206 ### Heavy Formatting 207 208 Avoid: 209 - Multiple levels of headers in short docs 210 - Excessive bold/italic 211 - Tables when lists suffice 212 - Code blocks for non-code 213 214 --- 215 216 ## File Naming 217 218 - Lowercase with hyphens: `style-guide.md` 219 - Dates in ISO format: `2026-01-14` 220 - Handoffs: `HANDOFF-{date}.md` 221 - Sessions: `{date}-{descriptor}.md` 222 223 --- 224 225 ## Recovery Footnote Format 226 227 Every Claude message ends with: 228 229 ``` 230 --- 231 handoff:: [[HANDOFF-{date}]] 232 branch:: {branch} 233 focus:: [[{Current Focus}]] | [[{Thread Anchor}]] 234 current:: {actual chat title} 235 ``` 236 237 --- 238 239 ## Linting 240 241 Run `scripts/lint-style.py` to check for violations: 242 243 ```bash 244 python scripts/lint-style.py patterns/*.md 245 python scripts/lint-style.py --fix patterns/*.md # Auto-fix where possible 246 ``` 247 248 Violations: 249 - `EMOJI` - Emoji character found 250 - `MARKDOWN_LINK_INTERNAL` - Use [[wikilink]] instead 251 - `PROPERTY_FORMAT` - Use `prop:: value` not `**Prop:** value` 252 253 --- 254 255 ## Rationale 256 257 1. **Obsidian compatibility** - Wikilinks and properties work in Obsidian graph view 258 2. **Queryability** - `::` properties can be searched/filtered 259 3. **Clean diffs** - Minimal formatting = cleaner git diffs 260 4. **Focus** - No visual noise from emojis