feat: enhance documentation guidelines with new heading and ToC policies, validation gates, and explanatory content requirements (#381)

Author: hannesrudolph

.roo/rules-documentation-writer/1_writing_style.xml

@@ -248,4 +248,64 @@
       </steps>
     </phase>
   </content_change_workflow>
+  <heading_and_toc_policy>
+    <overview>Minimize right-sidebar ToC noise. Reserve H3 for jump-worthy anchors and prefer H4 for in-body sub-chunking.</overview>
+    <rules>
+      <rule>H1 is implicit (page title). Do not write H1 in the body.</rule>
+      <rule>H2 = primary sections; aim for 3–6 per page.</rule>
+      <rule>H3 = ToC-worthy anchors only. Target 0–2 per page; hard cap 4.</rule>
+      <rule>H4 = break up long H2 sections without adding ToC items. Prefer H4 over H3 for minor subtopics.</rule>
+      <rule>Disallow H5/H6 entirely.</rule>
+      <rule>No orphan headings: any H2/H3/H4 must be followed by ≥2 sentences or a list.</rule>
+      <rule>Any H3 under ~75 words or a single short paragraph must be demoted to H4 .</rule>
+      <rule>Convert chains of small H3s into a single H2 with a numbered list; use H4 callouts if needed.</rule>
+      <rule>If an H4 exceeds ~200–250 words or needs substructure, split it into its own page (new H2 there) rather than promoting inside the same page.</rule>
+    </rules>
+    <budgets>
+      <page_h2>3–6</page_h2>
+      <total_h3>typical ≤ 2, max 4</total_h3>
+    </budgets>
+    <author_workflow>
+      <step>Outline H2 skeleton first.</step>
+      <step>Mark jump-worthy items as H3 only if sidebar navigation helps.</step>
+      <step>Everything else becomes H4 under the H2.</step>
+      <step>Preview ToC; demote noisy H3s to H4s before publishing.</step>
+    </author_workflow>
+    <example name="checkpoints_restructure">
+      <description>Demote unnecessary H3s under “Working with Checkpoints”.</description>
+      <before>
+## Working with Checkpoints
+### Viewing Differences
+### Restoring Checkpoints
+### Limitations and Considerations
+      </before>
+      <after>
+## Working with Checkpoints
+#### Viewing differences: when it helps
+#### Restore a checkpoint: trade-off
+#### Limits and gotchas
+      </after>
+    </example>
+  </heading_and_toc_policy>
+
+  <explanatory_baseline>
+    <requirement when="applicable">Include sections: “Why it matters”, “What you can’t do (and why)”, and “Troubleshooting”.</requirement>
+    <troubleshooting_pattern>
+      <item>symptom</item>
+      <item>cause</item>
+      <item>fix</item>
+      <item>prevention</item>
+    </troubleshooting_pattern>
+  </explanatory_baseline>
+
+  <tone_guidelines>
+    <rules>
+      <rule>Colloquial, informal, light. Use contractions and “you” voice.</rule>
+      <rule>Bold, honest, human—avoid mechanical or professoral tone.</rule>
+    </rules>
+  </tone_guidelines>
+
+  <screenshot_caption_policy>
+    <requirement>Every screenshot must include a one-line “why this view matters” caption in addition to outcome-focused alt text.</requirement>
+  </screenshot_caption_policy>
 </writing_style_guide>

.roo/rules-documentation-writer/2_docusaurus_conventions.xml

@@ -57,10 +57,10 @@
       </policy>
 
       <example>
-        <![CDATA[
+        
  <!-- First discover the actual image path structure, then use it -->
  <img src="/img/installing/installing-2.png" alt="VS Code's Install from VSIX dialog" width="600" />
-        ]]>
+        
       </example>
     </rule>
   </media>
@@ -85,7 +85,7 @@
         <step>Follow the established pattern</step>
       </discovery_steps>
       <example>
-        <![CDATA[
+        
 ---
 description: A concise summary of the page content.
 keywords:
@@ -95,7 +95,7 @@ keywords:
   - search
 image: /img/social-share.jpg
 ---
-        ]]>
+        
       </example>
     </rule>
   </frontmatter>
@@ -135,7 +135,7 @@ image: /img/social-share.jpg
         - File paths discovered
       </validation_requirement>
       <example>
-        <![CDATA[
+        
 <!-- MANDATORY: Search with multiple variations -->
 <codebase_search>
 <query>authentication setup configuration</query>
@@ -153,7 +153,7 @@ image: /img/social-share.jpg
 <query>user access credentials permissions</query>
 <path>docs</path>
 </codebase_search>
-        ]]>
+        
       </example>
     </step>
 
@@ -337,7 +337,7 @@ image: /img/social-share.jpg
       <scenario>When the impact on other documents is unclear</scenario>
     </scenarios>
     <example>
-      <![CDATA[
+      
 <ask_followup_question>
 <question>I found existing content about this topic in three different locations. How would you like me to proceed?</question>
 <follow_up>
@@ -347,7 +347,39 @@ image: /img/social-share.jpg
 <suggest>Show me the existing locations first so I can decide</suggest>
 </follow_up>
 </ask_followup_question>
-      ]]>
+      
     </example>
   </ask_before_proceeding>
+  <headings>
+    <overview>Control sidebar ToC noise and standardize heading usage.</overview>
+    <rules>
+      <rule>H1 comes from the page title; do not include H1 in body content.</rule>
+      <rule>Use H2 for primary sections (aim for 3–6 per page).</rule>
+      <rule>Use H3 only for ToC-worthy anchors users may want to jump to (target 0–2; hard cap 4 per page).</rule>
+      <rule>Prefer H4 for in-body sub-chunking so minor topics don’t pollute the ToC.</rule>
+      <rule>Disallow H5/H6 entirely.</rule>
+      <rule>No orphan headings: any H2/H3/H4 must be followed by at least two sentences or a list.</rule>
+      <rule>Any H3 under ~75 words or a single short paragraph must be demoted to H4 under its H2.</rule>
+      <rule>Convert chains of small H3s into one H2 with a numbered list; optional H4 callouts for sub-points.</rule>
+    </rules>
+    <toc_noise_standard>Total H3 ≤ 4 (typical ≤ 2). Demote non‑essential H3s to H4.</toc_noise_standard>
+    <example name="demote_h3_to_h4">
+      <before>
+## Working with Checkpoints
+### Viewing Differences
+### Restoring Checkpoints
+### Limitations and Considerations
+      </before>
+      <after>
+## Working with Checkpoints
+#### Viewing differences: when it helps
+#### Restore a checkpoint: trade-offs
+#### Limits and gotchas
+      </after>
+    </example>
+  </headings>
+
+  <media_adjustments>
+    <caption_requirement>Each screenshot must have a one‑line “why this view matters” caption in addition to outcome‑focused alt text. Use screenshots only for complex states or decision points; keep limits ≤1 per section and ≤3 per page.</caption_requirement>
+  </media_adjustments>
 </docusaurus_conventions>

.roo/rules-documentation-writer/3_validation_enforcement.xml

@@ -133,6 +133,54 @@
         - Get approval before proceeding
       </enforcement>
     </gate>
+    <gate name="toc_noise_gate" type="BLOCKING">
+      <description>Prevents noisy sidebars and redundant anchors.</description>
+      <requirements>
+        <requirement>Total H3 ≤ 4 (typical ≤ 2)</requirement>
+        <requirement>Demote non-essential H3s to H4 under the parent H2</requirement>
+        <requirement>No orphan headings (H2/H3/H4 must be followed by ≥2 sentences or a list)</requirement>
+      </requirements>
+      <enforcement>
+        If limits are exceeded or headings are orphaned:
+        - Demote H3s to H4 under the parent H2 before proceeding.
+      </enforcement>
+    </gate>
+
+    <gate name="heading_depth_gate" type="CRITICAL">
+      <description>Restricts heading depth.</description>
+      <requirements>
+        <requirement>Allow only H2–H4</requirement>
+        <requirement>Reject H5/H6</requirement>
+      </requirements>
+      <enforcement>
+        Any H5/H6 usage blocks the edit until replaced or removed.
+      </enforcement>
+    </gate>
+
+    <gate name="thin_subsection_blocker" type="BLOCKING">
+      <description>Prevents shallow ToC items.</description>
+      <requirements>
+        <requirement>Any H3 under ~75 words or a single short paragraph must be demoted to H4 under its H2</requirement>
+      </requirements>
+    </gate>
+
+    <gate name="explanatory_content_gate" type="BLOCKING">
+      <description>Requires explanatory sections when applicable.</description>
+      <requirements>
+        <requirement>Include “Why it matters”</requirement>
+        <requirement>Include “What you can’t do (and why)” when applicable</requirement>
+        <requirement>Include “Troubleshooting” using symptom → cause → fix → prevention when applicable</requirement>
+      </requirements>
+    </gate>
+
+    <gate name="screenshot_selectivity_gate" type="BLOCKING">
+      <description>Enforces complex-state-only screenshots and caption/alt-text quality.</description>
+      <requirements>
+        <requirement>Use screenshots only for complex states or decision points</requirement>
+        <requirement>Provide outcome-focused alt text and a one-line “why this view matters” caption</requirement>
+        <requirement>Respect limits: ≤1 per section, ≤3 per page</requirement>
+      </requirements>
+    </gate>
   </validation_gates>
 
   <mandatory_workflows>
@@ -182,7 +230,7 @@
   <user_communication_requirements>
     <requirement type="validation_reporting">
       <description>MUST report validation findings before making changes</description>
-      <template><![CDATA[
+      <template>
 <ask_followup_question>
 <question>I've completed the mandatory validation process. Here are my findings:
 
@@ -207,7 +255,7 @@ Should I proceed with this approach?</question>
 <suggest>Consolidate the scattered content instead</suggest>
 </follow_up>
 </ask_followup_question>
-      ]]></template>
+      </template>
     </requirement>
   </user_communication_requirements>
 

.roomodes

@@ -51,17 +51,20 @@ customModes:
     roleDefinition: |-
       You are Roo Code, a documentation specialist who writes only what matters.
       Core behaviors:
-      - Value-first: explain why before how; cut anything users can infer from the UI.
-      - Bold, honest voice: direct, punchy, zero fluff; never fake hype.
-      - Developer audience: precise, actionable, minimal steps.
-      - Enforce the rules in .roo/rules-documentation-writer/ (writing style, value filter, screenshot policy).
-      - Prefer consolidation over duplication; link to authoritative sources.
+      - Explanatory first: tell users why, why not, and how to recover (troubleshooting).
+      - Minimal ToC noise: H2 for primary sections; H3 only for jump-worthy anchors (max 4 per page, typically <= 2); prefer H4 for in-body sub-chunking; disallow H5/H6.
+      - Merge thin subsections and convert step chains into numbered lists under their H2.
+      - Bold, honest, human voice with contractions; informal and clear, not professoral.
+      - Selective screenshots: only for complex states/decisions; require outcome-focused alt text and a one-line "why this matters" caption.
+      - Prefer consolidation over duplication; link to the single source of truth.
+      - Enforce .roo/rules-documentation-writer/ policies (writing style, headings/structure, Docusaurus conventions, validation gates).
     whenToUse: |-
-      Use this mode to create or refine technical docs (.md/.mdx) with a value-first approach.
+      Use this mode to create or refine technical docs (.md/.mdx) with an explanatory, value-first approach and a clean, minimal ToC.
       Triggers:
-      - Pages drifting into UI narration or screen-by-screen walkthroughs
-      - Need for concise "why it matters / what you can do" structure
-      - Requests to add screenshots or restructure content for clarity
+      - Pages with noisy right-sidebar ToCs or overuse of H3s
+      - Requests to restructure into H2 sections with H4 sub-chunks and numbered lists
+      - Need to add "Why it matters / What you can't do (and why) / Troubleshooting"
+      - Requests to add or prune screenshots for complex states/decisions
     description: Creates and maintains Roo technical docs.
     groups:
       - read