Add validation cohesion checking and enhance release notes workflow (#282)

Author: hannesrudolph

.roo/rules-docs/1_writing_style.xml

@@ -3,6 +3,15 @@
     This guide defines the writing style for Roo Code documentation. The style is direct, concise, and technical. It avoids marketing language and prioritizes clarity for a developer audience. All output must be in markdown.
   </overview>
 
+  <discovery_principle>
+    <rule>Before writing or editing documentation, always explore existing documentation to understand established patterns, style, and structure.</rule>
+    <steps>
+      <step>Use list_files to explore the documentation structure</step>
+      <step>Read similar existing documents to understand the style</step>
+      <step>Follow established patterns rather than imposing new ones</step>
+    </steps>
+  </discovery_principle>
+
   <core_principles>
     <principle name="directness">
       <rule>Start with the most important information. No filler introductions.</rule>
@@ -17,11 +26,17 @@
     </principle>
     <principle name="consistency">
       <rule>When editing a document, use its existing style, structure, and format as a guideline for any updates. Do not make major changes unless explicitly asked.</rule>
+      <discovery_approach>
+        <step>Read the entire document first to understand its current style</step>
+        <step>Identify patterns in headings, formatting, and tone</step>
+        <step>Match the existing style in your edits</step>
+      </discovery_approach>
     </principle>
   </core_principles>
 
   <banned_language>
     <description>Avoid marketing jargon, buzzwords, and clichés. These words are ambiguous and reduce signal.</description>
+    <discovery_note>When editing existing documentation, check if any of these words are already used and maintain consistency with the existing approach.</discovery_note>
     <words>
       <word>seamlessly</word>
       <word>comprehensive</word>
@@ -42,5 +57,21 @@
     <guideline>Use structured headings, lists, and short paragraphs for scannability.</guideline>
     <guideline>Provide clear, copy-pasteable code snippets.</guideline>
     <guideline>Assume user familiarity with basic concepts. Do not over-explain.</guideline>
+    <discovery_approach>
+      <step>Before formatting new content, examine existing documentation for:
+        - Heading hierarchy patterns (H1, H2, H3 usage)
+        - List formatting preferences (bullets vs numbers)
+        - Code block styling and language tags
+        - Paragraph length and structure
+      </step>
+      <step>Match the discovered patterns to maintain consistency</step>
+    </discovery_approach>
   </formatting>
+
+  <before_writing_checklist>
+    <item>Have I explored the existing documentation structure?</item>
+    <item>Have I read similar documents to understand the established style?</item>
+    <item>Have I identified the patterns for paths, links, and references?</item>
+    <item>Am I following discovered patterns rather than making assumptions?</item>
+  </before_writing_checklist>
 </writing_style_guide>

.roo/rules-docs/2_docusaurus_conventions.xml

@@ -1,26 +1,43 @@
 <docusaurus_conventions>
   <overview>
-    This guide covers Docusaurus-specific formatting rules for Roo Code documentation.
+    This guide covers Docusaurus-specific formatting rules for Roo Code documentation. Before applying these conventions, always explore the project structure to understand the actual directory layout.
   </overview>
 
+  <discovery_first>
+    <principle>Always use list_files to discover the actual project structure before making assumptions about paths</principle>
+    <principle>Check for existing patterns in similar files before creating new content</principle>
+    <principle>Verify directory existence before referencing specific paths</principle>
+  </discovery_first>
+
   <linking>
     <rule name="internal_links">
-      <description>Use absolute paths from `/docs/`. Do not include the `.md` extension.</description>
+      <description>Use paths relative to the documentation root. Do not include the `.md` extension. Discover the documentation structure first.</description>
+      <discovery_steps>
+        <step>Use list_files to find the documentation root directory</step>
+        <step>Identify the path structure used in existing documentation</step>
+        <step>Follow the established pattern</step>
+      </discovery_steps>
       <good>[Link to Guide](/intro/)</good>
       <bad>[Link to Guide](../intro.md)</bad>
     </rule>
     <rule name="site_alias">
       <description>Use `@site` for code imports or asset references from the project root. Do not use it for Markdown links.</description>
-      <good>import Header from \'@site/src/components/Header\';</good>
+      <good>import Header from '@site/src/components/Header';</good>
       <bad>[Link](@site/docs/intro.md)</bad>
     </rule>
   </linking>
 
   <media>
     <rule name="images">
-      <description>Place images in `/static/img/`. Use a relative path in `src`.</description>
+      <description>Discover the image storage location in the project before placing images. Look for existing image references to understand the pattern.</description>
+      <discovery_steps>
+        <step>Use list_files to find where images are stored (commonly in static/img or similar)</step>
+        <step>Check existing documentation for image reference patterns</step>
+        <step>Follow the established convention</step>
+      </discovery_steps>
       <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>
@@ -29,12 +46,23 @@
 
   <versioning>
     <rule name="no_version_numbers">
-      <description>Do not include version numbers or phrases like "as of version X.Y" in general documentation. Version information belongs only in `docs/update-notes`.</description>
+      <description>Do not include version numbers or phrases like "as of version X.Y" in general documentation. First discover where version information is stored in the project.</description>
+      <discovery_steps>
+        <step>Use list_files to find version-related documentation directories</step>
+        <step>Check for patterns like update-notes, changelog, or release directories</step>
+        <step>Place version-specific information in the appropriate location</step>
+      </discovery_steps>
     </rule>
   </versioning>
+
   <frontmatter>
     <rule name="metadata">
-      <description>All pages must include frontmatter with description, keywords, and a social share image. The title will be automatically generated from the first H1 heading.</description>
+      <description>Check existing documentation files for frontmatter patterns before adding new ones. The required fields may vary by project.</description>
+      <discovery_steps>
+        <step>Read several existing documentation files to understand the frontmatter pattern</step>
+        <step>Identify which fields are consistently used</step>
+        <step>Follow the established pattern</step>
+      </discovery_steps>
       <example>
         <![CDATA[
 ---
@@ -50,4 +78,12 @@ image: /img/social-share.jpg
       </example>
     </rule>
   </frontmatter>
+
+  <general_discovery_workflow>
+    <step number="1">Use list_files to explore the project structure</step>
+    <step number="2">Read existing files similar to what you're creating/editing</step>
+    <step number="3">Identify patterns in paths, formatting, and conventions</step>
+    <step number="4">Follow the established patterns rather than assuming standard locations</step>
+    <step number="5">When in doubt, ask for clarification rather than making assumptions</step>
+  </general_discovery_workflow>
 </docusaurus_conventions>