From d9405b83d929f66d2ddc4eb26a61c2b40942eb32 Mon Sep 17 00:00:00 2001 From: Christophe Capel Date: Sun, 22 Mar 2026 15:32:59 +1100 Subject: [PATCH] fix: add markdown formatting rules to prevent coaching_state.md rendering issues Adds a "Markdown Formatting Rules" section under State Update Triggers that enforces: - Blank lines before ## and ### headings (CommonMark requirement) - Blank lines after closing tags - Table separator rows after every table header - Proper nesting of
blocks within parent toggles These rules prevent a class of formatting bugs where AI-generated markdown renders correctly in some parsers but breaks on GitHub's strict CommonMark. Co-Authored-By: Claude Opus 4.6 (1M context) --- SKILL.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/SKILL.md b/SKILL.md index e6a79d6..ec156b4 100644 --- a/SKILL.md +++ b/SKILL.md @@ -348,6 +348,15 @@ Write to `coaching_state.md` whenever: - Meta-check conversations (record candidate's response and any coaching adjustment to Meta-Check Log) - Any session where the candidate reveals coaching-relevant personal context — preferences, emotional patterns, interview anxieties, scheduling preferences, etc. (add to Coaching Notes) +### Markdown Formatting Rules (enforced on every state write) + +Every write to `coaching_state.md` must follow these rules to ensure correct rendering on GitHub (CommonMark): + +- **Blank line before headings:** Always insert a blank line before any `##` or `###` heading. Without it, the heading renders as inline text. +- **Blank line after `
`:** Always insert a blank line after any `` closing tag. Content immediately after a closing tag may not render correctly. +- **Table separator rows:** Every markdown table must have a separator row (`|---|---|...`) immediately after the header row. A header row without a separator renders as plain text, not a table. +- **Nested `
` blocks:** When content belongs within a parent `
` toggle (e.g., Take-Home Prep within a company's Interview Loop entry), place the nested `
` block before the parent's `
` tag, not as a sibling. + --- ## Non-Negotiable Operating Rules