aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCraig Jennings <c@cjennings.net>2026-05-25 00:41:02 -0500
committerCraig Jennings <c@cjennings.net>2026-05-25 00:41:02 -0500
commit9ebd26de52421b0d2515b2288d108278893d51e9 (patch)
treefda85fb1143ee657f7e0b0570e99c65391d74c04
parent086d5c880324e9c7eeb57606f86fd081bba8e85c (diff)
downloadrulesets-9ebd26de52421b0d2515b2288d108278893d51e9.tar.gz
rulesets-9ebd26de52421b0d2515b2288d108278893d51e9.zip
docs: keep chat output plain text to avoid reverse-video
Craig's terminal renders Markdown bold and inline-code spans as reverse video, which is hard to read. I added a rule to interaction.md: in conversational output, write command names, paths, and key chords as plain text, and lean on headers, dashes, parentheses, and quotes for structure. It governs chat output only, not the Markdown source of the rule and spec files he reads in an editor. I also made the keybinding-display example plain text so the convention shows the format the way it should appear in chat, with a pointer to the new rule.
-rw-r--r--claude-rules/interaction.md14
-rw-r--r--claude-rules/keybinding-display.md26
2 files changed, 29 insertions, 11 deletions
diff --git a/claude-rules/interaction.md b/claude-rules/interaction.md
index 4d9279b..7e42c44 100644
--- a/claude-rules/interaction.md
+++ b/claude-rules/interaction.md
@@ -29,3 +29,17 @@ For multi-select decisions, say so explicitly: "Pick any combination — reply w
Reserve `AskUserQuestion` only when the user explicitly asks for the popup form ("use the popup for this one") or for genuinely free-form input where numbered options don't fit.
This rule applies to all three approval gates in the `commits.md` publish flow (commit message, PR description, PR review reply): print the draft inline, then offer numbered approve / changes / edit options inline. Do not switch to the popup form for the gate even though the prior protocol referenced it.
+
+## No Reverse-Video Highlighting in Chat Output
+
+In conversational output to the user, do not use Markdown bold (`**...**`) or inline-code spans (backtick `` `...` ``). The user's terminal renders both as reverse video, which is hard to read on the display.
+
+**Why:** The styling that looks like emphasis in most renderers comes through as inverted foreground/background here. Plain prose, plain identifiers, and plain key chords read cleanly; the "highlight" actively hurts legibility.
+
+**How to apply:**
+
+- Write command names, file paths, key chords, and code identifiers as plain text — `pearl-save-issue` becomes pearl-save-issue, `C-; L s s` becomes C-; L s s.
+- Use structure that doesn't invert colors: headers, numbered lists, dashes, parentheses, and double quotes for labels are all fine.
+- Fenced code blocks (triple backtick) are acceptable when the user explicitly wants a block to copy — they don't invert the way inline spans do. Default to plain text otherwise.
+
+This governs **chat output**, not the Markdown source of rule files, specs, or docs the user reads in an editor — those keep normal Markdown formatting. The constraint is the terminal rendering of the live conversation.
diff --git a/claude-rules/keybinding-display.md b/claude-rules/keybinding-display.md
index 6c5d4b3..ad45720 100644
--- a/claude-rules/keybinding-display.md
+++ b/claude-rules/keybinding-display.md
@@ -16,22 +16,26 @@ A bulleted list grouped by **category**, where each category is one level of the
- *Which-key label* — the short string that shows in the which-key popup, in quotes (`"save ticket"`). For a sub-prefix, use the which-key prefix label (`"+save"`).
- **General comes first**, then one section per sub-category in a sensible order.
+## Plain text in chat
+
+Render this in chat as plain text — no Markdown bold and no inline-code spans. Headers, dashes, parentheses, and double-quoted labels carry the structure without them. See the "No Reverse-Video Highlighting in Chat Output" rule in [`interaction.md`](interaction.md): bold and backtick spans invert to reverse video on the user's terminal. The example below is shown the way it should appear in chat.
+
## Example
-For an imaginary command set `Pearl` on base prefix `C-; L`:
+For an imaginary command set Pearl on base prefix C-; L:
-**Pearl General — `C-; L`:**
-- `C-; L s` — *(Save prefix)* — "+save"
-- `C-; L e` — *(Edit prefix)* — "+edit"
-- `C-; L m` — `pearl-menu` — "menu"
+Pearl General — C-; L:
+- C-; L s — (save prefix) — "+save"
+- C-; L e — (edit prefix) — "+edit"
+- C-; L m — pearl-menu — "menu"
-**Pearl Save — `C-; L s`:**
-- `C-; L s s` — `pearl-save-issue` — "save ticket"
-- `C-; L s a` — `pearl-save-all` — "save all"
+Pearl Save — C-; L s:
+- C-; L s s — pearl-save-issue — "save ticket"
+- C-; L s a — pearl-save-all — "save all"
-**Pearl Edit — `C-; L e`:**
-- `C-; L e p` — `pearl-set-priority` — "priority"
-- `C-; L e s` — `pearl-set-state` — "state"
+Pearl Edit — C-; L e:
+- C-; L e p — pearl-set-priority — "priority"
+- C-; L e s — pearl-set-state — "state"
## Why