feat: enhance documentation workflow with detailed review processes and user feedback mechanisms

Author: hannesrudolph

.roo/rules-docs-extractor/1_extraction_workflow.xml

@@ -10,12 +10,13 @@
     <step number="1">
       <title>Understand Documentation Request</title>
       <actions>
-        <action>Parse the user's request to identify the feature or component</action>
-        <action>Default to user-friendly documentation unless technical docs are specifically requested</action>
-        <action>Focus on practical benefits and real-world usage</action>
-        <action>Note any specific aspects the user wants emphasized</action>
+        <action>Parse the user's request to identify the feature or component.</action>
+        <action>Determine if the user has provided a documentation section for review or is requesting new documentation.</action>
+        <action>Default to user-friendly documentation unless technical docs are specifically requested.</action>
+        <action>Focus on practical benefits and real-world usage.</action>
+        <action>Note any specific aspects the user wants emphasized.</action>
       </actions>
-      <note>The user will specify what they want documented in their initial message - no need to ask</note>
+      <note>The user will specify what they want documented in their initial message. The workflow branches based on whether a review is requested or new documentation is to be generated.</note>
     </step>
 
     <step number="2">
@@ -201,47 +202,26 @@
   </analysis_phases>
 
   <documentation_generation>
+    <note>This phase has two paths: Reviewing existing docs or Generating new docs. The path taken is determined in the initialization phase.</note>
     <step number="1">
-      <title>Choose Documentation Style</title>
+      <title>Path 1: Review and Recommend Improvements</title>
+      <note>This path is followed if the user provided a documentation section for review.</note>
       <actions>
-        <action>Default to user-focused template for end-user features</action>
-        <action>Use comprehensive template only for developer APIs or complex systems</action>
-        <action>Prioritize clarity and practical examples over exhaustive detail</action>
+        <action>Compare the provided documentation against the analysis of the codebase.</action>
+        <action>Identify inaccuracies (technical, logical), omissions, and areas for improvement.</action>
+        <action>Categorize inaccuracies by severity (e.g., Critical, Major, Minor, Suggestion).</action>
+        <action>Formulate a structured recommendation in the chat, suitable for being copied to the docs team.</action>
+        <action>Do not write any files or make changes yourself.</action>
       </actions>
-      <decision_criteria>
-        <criterion>If feature is user-facing → Use user_focused_template</criterion>
-        <criterion>If feature is developer API → Consider comprehensive_template</criterion>
-        <criterion>If unclear → Ask user for preference</criterion>
-      </decision_criteria>
     </step>
-
     <step number="2">
-      <title>Structure Documentation</title>
-      <actions>
-        <action>Start with clear problem statement and benefits</action>
-        <action>Use before/after examples when applicable</action>
-        <action>Keep technical details minimal unless essential</action>
-        <action>Focus on common use cases and questions</action>
-      </actions>
-    </step>
-
-    <step number="3">
-      <title>Generate Markdown Output</title>
-      <actions>
-        <action>Create DOCS-TEMP-[feature].md file</action>
-        <action>Use conversational tone and active voice</action>
-        <action>Include visual separators (---) between sections</action>
-        <action>Add practical examples and troubleshooting tips</action>
-      </actions>
-    </step>
-
-    <step number="4">
-      <title>Add User-Friendly Elements</title>
+      <title>Path 2: Generate New Documentation</title>
+      <note>This path is followed if the user requested new documentation.</note>
       <actions>
-        <action>Include "Why This Matters" section with real scenarios</action>
-        <action>Add "Common Questions" in Q&A format</action>
-        <action>Provide clear troubleshooting steps</action>
-        <action>End with "Need Help?" section pointing to resources</action>
+        <action>Choose a documentation style (e.g., user-focused or comprehensive) from `2_documentation_patterns.xml`.</action>
+        <action>Structure the documentation with clear sections, examples, and user-friendly elements.</action>
+        <action>Create a `DOCS-TEMP-[feature].md` file with the generated content.</action>
+        <action>Use a conversational tone and practical examples from `7_user_friendly_examples.xml`.</action>
       </actions>
     </step>
   </documentation_generation>

.roo/rules-docs-extractor/4_tool_usage_guide.xml

@@ -120,7 +120,8 @@
 
   <documentation_generation_tools>
     <tool name="write_to_file">
-      <purpose>Create the final documentation file</purpose>
+      <purpose>Create the final documentation file when generating new documentation from scratch.</purpose>
+      <note>This tool is NOT used when reviewing a user-provided document section. In that scenario, feedback is provided directly in the chat.</note>
       <file_naming>DOCS-TEMP-[feature-name].md</file_naming>
       <best_practices>
         <practice>Use descriptive feature names in filename</practice>

.roo/rules-docs-extractor/5_complete_extraction_examples.xml

@@ -821,10 +821,58 @@ DEBUG=auth:* npm start
       </step>
     </workflow>
   </example>
+  <example name="documentation_review_example">
+    <scenario>
+      Review a user-provided documentation section for accuracy against the codebase
+      and provide recommendations for improvement in the chat.
+    </scenario>
+    <workflow>
+      <step number="1">
+        <description>User provides documentation for review</description>
+        <user_input>
+          "Here's our current draft for the JWT_SECRET setting. Can you check it for accuracy? 'The `JWT_SECRET` is an optional key for enhancing security.'"
+        </user_input>
+      </step>
+      <step number="2">
+        <description>Analyze relevant code</description>
+        <tool_use><![CDATA[
+<codebase_search>
+<query>JWT_SECRET configuration implementation</query>
+</codebase_search>
+        ]]></tool_use>
+        <expected_findings>
+          - Code where `JWT_SECRET` is read (e.g., `process.env.JWT_SECRET`)
+          - Logic that fails if the secret is missing
+          - Default values or error handling related to the secret
+        </expected_findings>
+      </step>
+      <step number="3">
+        <description>Formulate and provide feedback in chat</description>
+        <tool_use><![CDATA[
+<attempt_completion>
+<result>
+I have reviewed the documentation section provided for the `JWT_SECRET` setting. Here are my recommendations for improvement:
+
+**Overall Assessment**: The current draft is critically inaccurate and could lead to security vulnerabilities if followed.
+
+**Recommendations for Improvement**:
 
-  <best_practices>
-    <practice name="comprehensive_coverage">
-      <description>Ensure all aspects are documented</description>
+*   **Critical Inaccuracy**:
+    *   The documentation states that `JWT_SECRET` is optional. However, the application will fail to start if it is not provided. It is a **required** setting for the application to function securely.
+    *   **Suggestion**: "The `JWT_SECRET` is a **required** environment variable used to sign and verify JSON Web Tokens. The application will not run without it."
+
+This feedback can be copied and pasted for your documentation team.
+</result>
+</attempt_completion>
+        ]]></tool_use>
+        <note>No file is written. The feedback is provided directly to the user in the chat interface.</note>
+      </step>
+    </workflow>
+  </example>
+ 
+   <best_practices>
+     <practice name="comprehensive_coverage">
+       <description>Ensure all aspects are documented</description>
       <checklist>
         <item>Technical implementation details</item>
         <item>Business logic and rules</item>

.roo/rules-docs-extractor/6_communication_guidelines.xml

@@ -64,6 +64,29 @@
           Warn about intricate dependency chains affecting the feature
         </discovery>
       </important_discoveries>
+      <review_findings>
+       <template><![CDATA[
+I have reviewed the documentation section provided. Here are my recommendations for improvement:
+
+**Overall Assessment**: [Brief summary of the document's quality]
+
+**Recommendations for Improvement**:
+
+*   **Critical Inaccuracies**:
+   *   [Inaccuracy 1]: The documentation states [X], but the code implements [Y].
+   *   [Inaccuracy 2]: ...
+
+*   **Major Omissions**:
+   *   The documentation is missing information about [Missing Feature/Concept].
+   *   ...
+
+*   **Suggestions for Clarity**:
+   *   The section on [Topic] could be clarified by [Suggestion].
+   *   ...
+
+This feedback can be copied and pasted for your documentation team.
+       ]]></template>
+      </review_findings>
     </findings_communication>
   </user_interaction>
 
@@ -244,6 +267,16 @@ I've completed the comprehensive documentation extraction for the authentication
 
 The documentation is structured for multiple audiences and includes all requested metadata, version information, and cross-references.
     ]]></example>
+    <example_review><![CDATA[
+I have completed the review of the provided documentation section.
+
+**Action Taken**:
+- Analyzed the provided text against the current codebase for accuracy.
+- Identified several areas for improvement and outlined them as a recommendation.
+
+**Next Steps**:
+- The detailed feedback has been provided in the chat. You can copy and paste it to your documentation team. No files were created.
+    ]]></example_review>
   </completion_message>
 
   <error_handling>