bew/dotfiles/bew-inline-callout-style

Inline Callout Style

Callout markers draw attention to secondary info that should stand out in prose. Use when careful reader might otherwise miss or skip the info. No hard limit on count — if callouts appear frequently, prose likely needs rewriting rather than more markers.

Keywords

Common keywords and intended semantics:

• NOTE: — context or secondary info reader should not miss; doesn't block progress.
• IMPORTANT: — hard constraint. Must be followed to produce correct output.
• WARNING: — risk. Bad outcome if ignored.
• TIP: — actionable shortcut or best practice. Use rarely.
• TRADEOFF: — competing forces with no single right answer; surfaces the tension.

List above is not exhaustive. Use other UPPERCASE keywords when none fit, as long as keyword clearly signals nature of callout (e.g. CONTEXT:, CAVEAT:, ASSUMPTION:). Prefer established keywords when they fit.

Rules

• Write keyword in plain text, not bold: WARNING: not **WARNING:**.
• Same-paragraph lines (no blank line) are attached to and part of callout.
• Blank line ends callout.
• A new keyword at the start of a line also ends the previous callout.

Adjacent callouts need no blank line between them when they are on the same topic.

• Parenthesized form (KEYWORD: ...): must be single line. Can appear inline

within another paragraph without blank line separator.

• Guideline: avoid callouts for regular prose or step descriptions careful

reader would not miss. Prefer rewriting unclear prose over adding markers.

Examples

Multi-line WARNING — blank line ends callout:

WARNING: Avoid `.opencode/skills/` for team repos — it locks the skill to
OpenCode only and blocks non-OC contributors.
 
NOTE: another callout on different topic, no longer part of the warning.
 
This line is no longer part of the note.

Parenthesized IMPORTANT inline in a paragraph:

Present the draft as a fenced block labeled with the artefact type.
(IMPORTANT: Always use 4 backticks so nested code blocks don't break formatting.)
Ask: *Does this match what you had in mind?*

Adjacent callouts, different keywords, same topic — no blank line between them:

NOTE: This rule applies only when the skill is loaded explicitly.
WARNING: Loading it in auto-load context produces undefined behaviour.