diff --git a/.roo/rules-documentation-writer/1_writing_style.xml b/.roo/rules-documentation-writer/1_writing_style.xml index e016ee65..9f34e022 100644 --- a/.roo/rules-documentation-writer/1_writing_style.xml +++ b/.roo/rules-documentation-writer/1_writing_style.xml @@ -1,116 +1,69 @@ - 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. + Writing style for Roo Code documentation. The goal is clarity and trust, not personality. + Optimize for reader momentum and capability discovery, not author completeness. + All output must be markdown. - - Before writing or editing documentation, always explore existing documentation to understand established patterns, style, and structure. - - Use list_files to explore the documentation structure - Read similar existing documents to understand the style - Follow established patterns rather than imposing new ones - - - - - MANDATORY: Before making ANY changes to existing documentation files, you MUST complete the redundancy validation workflow. This is NOT optional. - - You CANNOT proceed with edits until validation is complete - You MUST document validation results before making changes - Skipping validation steps will result in task rejection - - - Use codebase_search to find ALL mentions of the topic across documentation - Search for multiple variations of key terms (e.g., if editing "authentication", also search "auth", "login", "security", "credentials") - Read and analyze EVERY discovered location thoroughly - Create a validation report listing: - - All locations where similar content exists - - The current state of each location - - Potential conflicts or duplications - - Recommendation for how to proceed - - If similar content exists, you MUST determine: - - Is this an update to existing content? (proceed to that location) - - Is this a consolidation opportunity? (merge content) - - Is this truly new, non-redundant content? (proceed with caution) - - - - Check for contradictions with existing documentation - Verify that new content aligns with established terminology and concepts - Ensure cross-references are accurate and bidirectional where appropriate - Validate that the change enhances rather than fragments the documentation flow - Document how the change improves overall documentation cohesion - - - You MUST use ask_followup_question to confirm validation results with the user BEFORE proceeding with any edits - - - - - - - Start with the most important information. No filler introductions. - In this guide, we will explore how to configure the tool. - To configure the tool, open... - - - Use short sentences. Cut unnecessary words. If it doesn't add value, remove it. - - - Focus on what the user can do and why it matters. Provide actionable steps. - - - Only document what actually exists. When it doubt, ask questions. - Invent inexistent features. - - - - Keep only what changes decisions, prevents mistakes, or unlocks outcomes. Cut narration of obvious UI. - - Why it matters (value/outcome; 1–3 sentences at the top) - Decision points and trade-offs (e.g., Pro vs free, security implications) - Non-obvious behavior, caveats, limits, prerequisites - Short, actionable steps; error handling and recovery - - - Listing every visible control or tab on a page - Describing screenshots (“This page shows…”, “It includes…”) without decisions or implications - Explaining basic concepts common to developers - Redundant restatement of labels already visible in screenshots - - - - - 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. - - Read the entire document first to understand its current style - Identify patterns in headings, formatting, and tone - Match the existing style in your edits - - - - - Bold, honest, human. No fluff, no fake hype. - - Short, punchy sentences. Speak like a helpful colleague. - Expose real value. If it matters, state it clearly; if not, leave it out. - Be excited when the feature earns it. Be candid about limits. - - - Don’t use buzzwords, clickbait, or corporate tone. - Don’t exaggerate beyond the truth—real impact sells itself. - Don’t narrate the screen. Focus on decisions and outcomes. - Don’t sell the product, describe its aparent value and mechanics. - - - - - - Avoid marketing jargon, buzzwords, and clichés. These words are ambiguous and reduce signal. - When editing existing documentation, check if any of these words are already used and maintain consistency with the existing approach. + + + Documentation sounds like a careful engineering teammate sitting next to you. + Calm, precise, focused on what will happen next. + It explains actions and consequences clearly and does not try to motivate, entertain, or reassure beyond what is factual. + + + + Help the user make a correct decision in the moment. + Every line should answer at least one of: + What is happening + Why it matters + What will happen if you proceed + What to do next if something fails + + + Documentation should read like a careful engineer describing system behavior, not like a product explaining itself. + + + + + Neutral + Direct + Predictable + Low emotion + + + No hype + No jokes + No clever phrasing + The UI is not a stage + + + + + + Short sentences + One idea per sentence + Active voice + Concrete verbs + + Fragments are acceptable if clearer than full sentences. + + + + + run, write, open, delete, stop, approve + file, branch, PR, task, command, log + will modify, will create, will stop + + + handle, manage, process + solution, intelligence, capability + might try to, could potentially + + + + + Avoid marketing jargon, buzzwords, and vague reassurance. seamlessly comprehensive @@ -125,137 +78,120 @@ easily simply - - - - Use structured headings, lists, and short paragraphs for scannability. - In step-by-step guides, use simple numbered lists. Don't use headings for numbered steps. - Provide clear, copy-pasteable code snippets. - Assume user familiarity with basic concepts. Do not over-explain. - In each page, after the initial introduction, add an HR with `---` before continuing. Use HRs sparingly outside of that. - - -
Explain the outcome and value in 1–3 sentences.
-
Concrete capabilities and decision points; link to authoritative references instead of duplication.
-
Minimal steps to success (include only non-obvious choices).
-
Common failure modes and fixes.
- - - - Only include screenshots when they clarify a decision, show non-obvious state, or demonstrate outcome. - - 3 - 6 - - - No narration of on-screen labels or obvious layout. - No screenshot that repeats text already stated without adding decision context. - - - Alt text describes action/outcome, not the UI chrome. - Prefer width="600" unless smaller improves readability. - Use captions or surrounding text to explain the decision/implication. - Follow Docusaurus image rules; see rules in 2_docusaurus_conventions.xml. - - - - - 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 - - Match the discovered patterns to maintain consistency - - - - - Have I explored the existing documentation structure? - Have I read similar documents to understand the established style? - Have I identified the patterns for paths, links, and references? - Am I following discovered patterns rather than making assumptions? - Have I searched for existing content that might overlap with my changes? - Have I verified that my changes don't contradict existing documentation? - Have I checked that cross-references will remain valid? - + + + + Be explicit when something is risky, slow, expensive, or irreversible. + Do not apologize for tradeoffs. State them. + + This will modify files in your workspace. + Stopping this task may leave partial changes. + Cloud execution costs more than local execution. + + + + + + State what failed + State why if known + Give one concrete next step + + + State the risk + State the scope + Ask for explicit confirmation + + No emotional language. No reassurance beyond facts. + + + + Guidance should explain what the system expects, not what the user should feel. + + What input is required + What constraints apply + What success looks like + + Avoid instructional fluff or encouragement. + + + + Use humor + Use marketing language + Use vague reassurance + Hide side effects + Speak about future plans or unshipped features + + + + + No fixed skeleton. Answer these questions in order, only if applicable. + Omit aggressively. If the page reads like a form, it failed. + + + What is the primary capability? + How do I use it in practice? + What choices or modes exist? + What can go wrong and how do I fix it? + Where do I go deeper? + + + Remove all mandatory section scaffolding. + Generate an outline based on feature complexity. + Prefer fewer sections with stronger titles. + Delete empty or obvious sections. + Optimize for a reader skimming at 10 seconds. + + + + + The first section must show what the feature does now. + Use examples, tables, or UI references. + Avoid conceptual framing unless needed. + Context follows behavior, not the reverse. + + + + Start with the default path. + Expand into modes, levels, or configuration only after baseline usage. + Troubleshooting is optional and last. + + + + + Convert the old skeleton into validation checks, not templates. + Fail only when a required answer is missing, not when a section is missing. + + + Does the page explain why this exists? (if non-obvious) + Does it show how to use it? + Does it document decisions the user must make? + Does it cover known failure modes? (if any exist) + + + + + Headings must name capabilities, not explanations. Be scannable in isolation. + + Name capabilities, not intent. + Match UI labels, commands, or mental models. + Be scannable in isolation. + + + + why_it_matters + what_you_can_do + Understanding the feature + + + Auto-executed Cascade commands + Allow and deny lists + Dedicated terminal + + + - - - This workflow is MANDATORY for ALL documentation changes. Each phase MUST be completed in order. - Skipping any phase or step will invalidate the entire change request. - - - - Analyze the requested change and its impact - You CANNOT proceed to the next phase until ALL steps are complete - - Identify the scope and purpose of the requested change - List ALL key concepts, terms, and their variations (e.g., "config" → "configuration", "setup", "settings") - Determine which documents might be affected (use list_files to verify) - Document your analysis results before proceeding - - - - - Search for ALL existing related content - this phase is NOT optional - You MUST find and analyze ALL related content before proceeding - - Use codebase_search with the primary term from the request - Use codebase_search with EACH variation of key terms identified in analysis - Read ALL potentially related documentation sections in full - Create a comprehensive map documenting: - - Every location where related information exists - - The specific content at each location - - How each location relates to the requested change - - Identify any gaps, overlaps, or contradictions - If you find existing content, you MUST read it completely before proceeding - - - - - Validate the change against existing content - MUST be completed before ANY edits - You MUST answer ALL questions and get user confirmation before implementation - - Does this exact information already exist elsewhere? (If yes, STOP and redirect to existing location) - Does similar but incomplete information exist? (If yes, enhance existing rather than duplicate) - Will this change create any contradictions with existing docs? - Have you verified ALL cross-references will remain valid? - Does this enhance the documentation flow or fragment it? - Have you identified ALL files that need updates to maintain consistency? - - - You MUST use ask_followup_question to present validation findings and get approval - Include specific file paths and line numbers in your validation report - Provide clear recommendations based on your findings - - - - - Apply changes ONLY after validation is approved by user - You can ONLY enter this phase after user approves validation results - - If updating existing content, preserve ALL valuable context - If adding new content, ensure it links appropriately to ALL related topics discovered in phase 2 - Update ALL affected cross-references in other documents - Maintain consistent terminology throughout ALL affected files - Verify no information is lost or contradicted by your changes - - - - - Verify the changes maintain documentation integrity - - Re-run codebase_search to ensure no duplicates were created - Verify all cross-references still work - Confirm terminology remains consistent - Document what was changed and why for future reference - - - - Minimize right-sidebar ToC noise. Reserve H3 for jump-worthy anchors and prefer H4 for in-body sub-chunking. + Minimize right-sidebar ToC noise. Reserve H3 for jump-worthy anchors; prefer H4 for in-body sub-chunking. H1 is implicit (page title). Do not write H1 in the body. H2 = primary sections; aim for 3–6 per page. @@ -263,9 +199,9 @@ H4 = break up long H2 sections without adding ToC items. Prefer H4 over H3 for minor subtopics. Disallow H5/H6 entirely. No orphan headings: any H2/H3/H4 must be followed by ≥2 sentences or a list. - Any H3 under ~75 words or a single short paragraph must be demoted to H4 . + Any H3 under ~75 words or a single short paragraph must be demoted to H4. Convert chains of small H3s into a single H2 with a numbered list; use H4 callouts if needed. - 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. + If an H4 exceeds ~200–250 words or needs substructure, split it into its own page rather than promoting inside the same page. 3–6 @@ -277,41 +213,40 @@ Everything else becomes H4 under the H2. Preview ToC; demote noisy H3s to H4s before publishing. - - Demote unnecessary H3s under “Working with Checkpoints”. - -## Working with Checkpoints -### Viewing Differences -### Restoring Checkpoints -### Limitations and Considerations - - -## Working with Checkpoints -#### Viewing differences: when it helps -#### Restore a checkpoint: trade-off -#### Limits and gotchas - - - - Include sections: “Why it matters”, “What you can’t do (and why)”, and “Troubleshooting”. - - symptom - cause - fix - prevention - - + + When troubleshooting is needed (optional, placed last): + symptom + cause + fix + prevention + - - - Colloquial, informal, light. Use contractions and “you” voice. - Bold, honest, human—avoid mechanical or professoral tone. - - + + Use structured headings, lists, and short paragraphs for scannability. + In step-by-step guides, use simple numbered lists. Do not use headings for numbered steps. + Provide clear, copy-pasteable code snippets. + Assume user familiarity with basic concepts. Do not over-explain. + After the initial introduction, add an HR with `---` before continuing. Use HRs sparingly outside of that. + + + + Before writing or editing, explore existing documentation to understand established patterns. + + Use list_files to explore the documentation structure + Read similar existing documents to understand the style + Follow established patterns rather than imposing new ones + + - - Every screenshot must include a one-line “why this view matters” caption in addition to outcome-focused alt text. - - \ No newline at end of file + + Have I explored the existing documentation structure? + Have I read similar documents to understand the established style? + Am I following discovered patterns rather than making assumptions? + Have I searched for existing content that might overlap with my changes? + Does the first section show what the feature does, not explain why it exists? + Are headings capability names, not abstract labels? + Can a reader scanning for 10 seconds find what they need? + + diff --git a/.roo/rules-documentation-writer/2_docusaurus_conventions.xml b/.roo/rules-documentation-writer/2_docusaurus_conventions.xml index 7fd5e8c5..48ff650b 100644 --- a/.roo/rules-documentation-writer/2_docusaurus_conventions.xml +++ b/.roo/rules-documentation-writer/2_docusaurus_conventions.xml @@ -1,6 +1,7 @@ - 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. + Docusaurus-specific formatting rules for Roo Code documentation. + Always explore the project structure to understand the actual directory layout before applying these conventions. @@ -11,7 +12,7 @@ - Use paths relative to the documentation root. Do not include the `.md` extension. Discover the documentation structure first. + Use absolute paths from the documentation root. Do not include the `.md` extension. Use list_files to find the documentation root directory Identify the path structure used in existing documentation @@ -29,9 +30,9 @@ - Discover the image storage location in the project before placing images. Look for existing image references to understand the pattern. + Discover the image storage location in the project before placing images. - Use list_files to find where images are stored (commonly in static/img or similar) + Use list_files to find where images are stored (commonly static/img) Check existing documentation for image reference patterns Follow the established convention @@ -42,7 +43,7 @@ Demonstrate outcome/results that text alone cannot convey - Narrating obvious UI (“This page shows…”, “It includes…”) without decisions or implications + Narrating obvious UI without decisions or implications Listing every field/tab in a screen @@ -52,22 +53,21 @@ Describe the action or outcome, not the chrome. Example: "Toggle Roomote Control to enable remote tasks". - 800 + Each screenshot must have a one-line "why this view matters" caption. + 600 Use HTML img tags per project rules. See Image Tag Format in .roorules. - - - VS Code's Install from VSIX dialog - + +VS Code's Install from VSIX dialog - 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. + Do not include version numbers or phrases like "as of version X.Y" in general documentation. Use list_files to find version-related documentation directories Check for patterns like update-notes, changelog, or release directories @@ -78,14 +78,13 @@ - Check existing documentation files for frontmatter patterns before adding new ones. The required fields may vary by project. + Check existing documentation files for frontmatter patterns before adding new ones. Read several existing documentation files to understand the frontmatter pattern Identify which fields are consistently used Follow the established pattern - --- description: A concise summary of the page content. keywords: @@ -94,11 +93,14 @@ keywords: - for - search --- - + + When moving or renaming docs, add an explicit redirect in docusaurus.config.ts under plugin-client-redirects. + + Use list_files to explore the project structure Read existing files similar to what you're creating/editing @@ -107,127 +109,6 @@ keywords: When in doubt, ask for clarification rather than making assumptions - - - This workflow is MANDATORY for ALL edits to existing documentation files - You CANNOT skip any step - each must be completed and documented - Failure to complete this workflow will result in rejection of changes - - - - CRITICAL: This workflow MUST be completed BEFORE making ANY changes to existing documentation. No exceptions. - - - - Comprehensive Content Discovery - You CANNOT proceed without completing ALL searches - - Use codebase_search with the exact topic/feature name - Use codebase_search with ALL variations of key terms (minimum 3-5 variations required) - Search for related concepts that might contain overlapping information - Document EVERY location found with file path and line numbers - - - You MUST provide evidence of searches performed: - - List each search query used - - Number of results found for each - - File paths discovered - - - - - -authentication setup configuration -docs - - - - -auth config login security -docs - - - - -user access credentials permissions -docs - - - - - - - Exhaustive Duplication Analysis - You MUST read EVERY discovered file before proceeding - - Read ALL discovered related content in full - no skimming - Create a detailed comparison table showing: - - What information exists where - - How it relates to the requested change - - Overlap percentage with requested content - - Identify if the requested change would duplicate ANY existing information - Document your findings in a structured format - - - - STOP immediately. Inform user with specific file location. DO NOT create duplicate content. - - - STOP creating new content. Enhance existing content at its current location instead. - - - STOP and propose consolidation plan to user before any edits. - - - Document this finding and proceed with caution to next step. - - - - - - Impact Analysis and Cross-Reference Validation - Complete impact analysis before ANY file modifications - - List ALL internal links that reference or might reference this content - Identify ALL files that would need updates if content is moved or changed - Check for hardcoded references in: - - Other documentation files - - Configuration files - - Code examples - - Tutorials or guides - - Create an impact report listing all affected files - Plan redirect updates for docusaurus.config.ts if needed - - - - - Terminology and Consistency Verification - - Create a terminology map of all technical terms used - Verify terms match existing usage across ALL documentation - Check glossary or terminology guide for standard definitions - Document any terminology conflicts found - - - - - User Approval Gate - You CANNOT proceed with edits without explicit user approval - - Present complete validation findings using ask_followup_question - Include: - - All discovered duplicate or related content with specific locations - - Impact analysis results - - Recommended approach (update existing, consolidate, or create new) - - List of all files that would be affected - - Wait for explicit user approval before making ANY changes - - - - Maintain logical information hierarchy and flow @@ -237,7 +118,7 @@ keywords: Does it follow the progression from basic to advanced? - + Each piece of information should have one authoritative location @@ -256,129 +137,9 @@ keywords: - - - This protocol is MANDATORY for ALL updates to existing documentation - Skipping any validation step will invalidate the entire update - - - - CRITICAL: When updating existing documentation, this protocol MUST be followed completely. No shortcuts allowed. - - - - You CANNOT begin updates until ALL validation steps are complete - Run codebase_search to identify ALL documents that reference the content being updated - Create a dependency map showing: - - Which files reference this content - - Which examples depend on this content - - Which tutorials or guides link to this content - - Read EVERY dependent file to understand impact - Verify that the update won't invalidate ANY existing instructions - Document backward compatibility concerns if features have changed - Create a comprehensive update plan BEFORE making any changes - - - - You MUST answer ALL questions with evidence before proceeding - Will this update require changes to other documents? List each file. - Are there code examples that need to be updated? Provide file paths. - Do any quickstart guides or tutorials reference this content? List them. - Will this change affect the logical flow of the documentation? Explain how. - Have you verified this won't create contradictions? Provide evidence. - - If ANY answer is "yes" or "maybe", you MUST: - 1. Document all required changes - 2. Get user approval for the full scope - 3. Update ALL affected files in the correct order - - - - - Only proceed after pre-update validation is complete and approved - Updates must be made in dependency order to prevent broken states - - Update the primary content first - Update all dependent content in order of dependency - Verify each update before proceeding to the next - Test all cross-references after each change - - - - - EVERY item must be verified before considering the update complete - Re-run codebase_search to verify all references are still valid - Test EVERY cross-reference link in affected documents - Verify NO broken links have been introduced (use search for old paths) - Confirm terminology remains consistent across ALL affected documents - Verify the update enhances rather than contradicts existing content - Ensure version-specific information is properly isolated - Document what was changed and why in a change log - - - - Use ask_followup_question to confirm all updates are complete and validated - Provide a summary of: - - All files that were updated - - All validation checks performed - - Any remaining concerns or follow-up needed - - - - - - Use ask_followup_question when uncertainty exists about redundancy or impact - - When similar content exists in multiple locations - When the requested change might contradict existing documentation - When consolidation might be better than addition - When the impact on other documents is unclear - - - - -I found existing content about this topic in three different locations. How would you like me to proceed? - -Update the main guide and add cross-references from the other locations -Consolidate all information into a single comprehensive guide -Keep them separate but ensure they're consistent and cross-linked -Show me the existing locations first so I can decide - - - - - - - Control sidebar ToC noise and standardize heading usage. - - H1 comes from the page title; do not include H1 in body content. - Use H2 for primary sections (aim for 3–6 per page). - Use H3 only for ToC-worthy anchors users may want to jump to (target 0–2; hard cap 4 per page). - Prefer H4 for in-body sub-chunking so minor topics don’t pollute the ToC. - Disallow H5/H6 entirely. - No orphan headings: any H2/H3/H4 must be followed by at least two sentences or a list. - Any H3 under ~75 words or a single short paragraph must be demoted to H4 under its H2. - Convert chains of small H3s into one H2 with a numbered list; optional H4 callouts for sub-points. - - Total H3 ≤ 4 (typical ≤ 2). Demote non‑essential H3s to H4. - - -## Working with Checkpoints -### Viewing Differences -### Restoring Checkpoints -### Limitations and Considerations - - -## Working with Checkpoints -#### Viewing differences: when it helps -#### Restore a checkpoint: trade-offs -#### Limits and gotchas - - - - - 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. - - \ No newline at end of file + + See 1_writing_style.xml for heading/ToC rules + See 3_validation_enforcement.xml for mandatory validation workflows + + diff --git a/.roo/rules-documentation-writer/3_validation_enforcement.xml b/.roo/rules-documentation-writer/3_validation_enforcement.xml index 5f1b78f7..4060dcde 100644 --- a/.roo/rules-documentation-writer/3_validation_enforcement.xml +++ b/.roo/rules-documentation-writer/3_validation_enforcement.xml @@ -1,290 +1,175 @@ - + - This document defines the strict enforcement rules and consequences for the documentation writer mode. - ALL validation steps are MANDATORY when editing existing documentation files. + Validation rules for documentation edits. Complete all validation steps before editing existing files. - - - Violations that result in immediate task rejection + + + Violations that result in task rejection - Skipping the redundancy prevention workflow when editing existing files - Making changes without completing content discovery searches - Creating duplicate content when similar content already exists - Proceeding with edits without user approval after validation + Skipping redundancy check when editing existing files + Creating duplicate content when similar content already exists + Proceeding with edits without user approval after validation - - Task is immediately rejected - All changes are reverted - Mode must restart from the beginning - - - + Issues that prevent progression until resolved - Incomplete validation checklist items - Missing impact analysis for cross-references - Failing to read all discovered related content - Not searching for term variations during discovery + Incomplete validation checklist + Missing impact analysis for cross-references + Not searching for term variations during discovery - - Cannot proceed to implementation phase - Must complete all missing steps - Must document completion of each step - - - + Issues that require correction but allow conditional progression - Inconsistent terminology usage - Missing bidirectional links - Incomplete post-update verification + Inconsistent terminology usage + Missing bidirectional links + Incomplete post-update verification - - Must acknowledge the issue - Must create a plan to address it - May proceed with user approval - - + + + + + Find all existing related content before making changes + + Use codebase_search with the primary topic/feature name + Search variations of key terms (e.g., "config" → "configuration", "setup", "settings") + Read all discovered related content thoroughly + Document locations with file paths and relevance + + + + + Determine how to proceed based on discovery + + + STOP. Inform user with specific file location. Do not create duplicate. + + + Enhance existing content at its current location. + + + Propose consolidation plan to user before edits. + + + Document finding and proceed to implementation. + + + + + + Identify all files affected by the change + + List internal links that reference this content + Identify files needing updates if content moves + Check hardcoded references in other docs, config files, code examples + Plan redirect updates for docusaurus.config.ts if needed + + + + + Get user confirmation before proceeding + Use ask_followup_question to present validation findings + + All discovered duplicate or related content with locations + Impact analysis results + Recommended approach + List of affected files + + + + + Apply changes only after approval + + If updating existing content, preserve valuable context + If adding new content, link to related topics discovered earlier + Update all affected cross-references + Maintain consistent terminology + + + + + Confirm changes maintain documentation integrity + + Re-run codebase_search to ensure no duplicates created + Verify all cross-references still work + Confirm terminology remains consistent + + + - - MANDATORY gate before ANY edits to existing files + + Before any edits to existing files - Must complete ALL content discovery searches - Must read ALL discovered related content - Must document validation findings - Must get explicit user approval to proceed + Complete content discovery searches + Read all discovered related content + Document validation findings + Get explicit user approval - - If ANY requirement is not met: - - You CANNOT make any edits - - You MUST inform the user what's missing - - You MUST complete missing steps before proceeding - - + Prevents creation of duplicate content - - If similar content exists, MUST update existing location - If content is scattered, MUST propose consolidation - CANNOT create new content if it duplicates existing - - - If duplicate content is detected: - - IMMEDIATELY STOP all work - - Report exact locations of existing content - - Redirect efforts to enhancing existing content - + + If similar content exists, update existing location + If content is scattered, propose consolidation + Never create new content if it duplicates existing + - - Enforces value-first writing and bans obvious-UI narration. + + Enforces value-first writing - Include a brief "Why it matters" section or opener (1–3 sentences) that frames value/outcomes. - Document decision points/trade-offs where the user must choose (e.g., Pro vs free, security implications). - Remove or condense any enumeration of on-screen elements unless each item carries a decision, consequence, or non-obvious behavior. - Apply screenshot limits (≤1 per section, ≤3 per page) and ensure alt text describes action/outcome. + Include "Why it matters" opener (1–3 sentences) + Document decision points and trade-offs + Remove UI narration that lacks decisions/implications + Respect screenshot limits (≤1/section, ≤3/page) - - Checklist confirming presence of "Why it matters" and decisions - Notes on removed UI narration and reasons - Screenshot count and alt-text review - - - If requirements are not met: - - Block the edit and return a summary of violations with specific locations. - - Require revision to pass this gate before proceeding. - - - Blocks screen narration that restates visible UI without adding decisions or implications. - - This page shows - It includes - The page displays - List of - - - Allowed only when each listed item includes why it matters, a decision, or an implication. - - - If narration-only content is detected: - - Remove or compress into a single contextual sentence tied to a decision or outcome. - - - - + Ensures documentation remains consistent - All terminology must match existing usage - All cross-references must remain valid + Terminology matches existing usage + Cross-references remain valid No contradictions with existing content - - If inconsistencies are found: - - Document all inconsistencies - - Create a resolution plan - - Get approval before proceeding - - - - Prevents noisy sidebars and redundant anchors. - - Total H3 ≤ 4 (typical ≤ 2) - Demote non-essential H3s to H4 under the parent H2 - No orphan headings (H2/H3/H4 must be followed by ≥2 sentences or a list) - - - If limits are exceeded or headings are orphaned: - - Demote H3s to H4 under the parent H2 before proceeding. - - - - - Restricts heading depth. - - Allow only H2–H4 - Reject H5/H6 - - - Any H5/H6 usage blocks the edit until replaced or removed. - - - - - Prevents shallow ToC items. - - Any H3 under ~75 words or a single short paragraph must be demoted to H4 under its H2 - - - - - Requires explanatory sections when applicable. - - Include “Why it matters” - Include “What you can’t do (and why)” when applicable - Include “Troubleshooting” using symptom → cause → fix → prevention when applicable - - - - - Enforces complex-state-only screenshots and caption/alt-text quality. - - Use screenshots only for complex states or decision points - Provide outcome-focused alt text and a one-line “why this view matters” caption - Respect limits: ≤1 per section, ≤3 per page - - - - MANDATORY workflow for ANY edit to existing documentation - - Run redundancy prevention workflow - Complete content discovery with multiple search terms - Read and analyze ALL discovered content - Create validation report with findings - Pass the Value Filter Gate and Obvious-UI Narration Blocker with documented evidence - Get user approval via ask_followup_question - Proceed with approved approach only - Verify all changes maintain consistency - - - Skipping ANY mandatory step results in: - - Immediate task rejection - - Requirement to restart from step 1 - - Documentation of the violation - - - - - - Documentation required to prove validation completion - - - List of all codebase_search queries performed - Query text, number of results, relevant findings - - - Summary of all discovered related content - File path, line numbers, content summary, relevance - - - List of all files affected by the change - File path, type of impact, required updates - - - Comprehensive report of all validation findings - Structured summary with recommendations - - - - - - - MUST report validation findings before making changes - - - - - - - Every validation step must be logged - - Timestamp of each step - Actions taken - Results found - Decisions made - - - - Every edit must have documented justification - - Why the change is needed - What validation was performed - How it improves documentation - What alternatives were considered - - - - - - - These enforcement rules are NOT optional. They are MANDATORY for ALL documentation edits. - The documentation writer mode MUST follow these rules without exception. - Failure to comply will result in task rejection and requirement to start over. - - - \ No newline at end of file +[Specific recommendation] + +**Affected Files:** +[Complete list] + +Should I proceed with this approach? + + + Yes, proceed with the recommended approach + No, let me provide different instructions + Show me the existing content first + Consolidate the scattered content instead + + + + + See 1_writing_style.xml for heading/ToC rules and enforcement + See 2_docusaurus_conventions.xml for screenshot format and limits + + diff --git a/.roo/rules-documentation-writer/4_audit_workflow.xml b/.roo/rules-documentation-writer/4_audit_workflow.xml new file mode 100644 index 00000000..1ac859e9 --- /dev/null +++ b/.roo/rules-documentation-writer/4_audit_workflow.xml @@ -0,0 +1,134 @@ + + + Workflow for auditing existing documentation against defined rules. + Triggered by: "cleanup", "review", "audit", "rewrite", or "improve" requests. + + + + cleanup this section + review this page + audit this doc + rewrite this + improve this section + what's wrong with this + + + + + Read the target content + Read the entire section, page, or content specified by the user. + + + + Run checklist against rules + Evaluate the content against each category in the audit_checklist below. + Mark each item as PASS, FAIL, or N/A. + + + + Generate findings report + Output a structured report with specific issues and suggestions. + Include line references or quotes where possible. + + + + Propose changes + Ask user if they want to proceed with suggested improvements. + If yes, apply changes following the validation workflow in 3_validation_enforcement.xml. + + + + + + Does the first section show what the feature does (not explain why it exists)? + Does the page answer: capability, usage, choices, failures, deeper links (only if applicable)? + Are empty or obvious sections deleted? + Can a reader scanning for 10 seconds find what they need? + Does it avoid feeling like a form with mandatory boxes? + + + + Do headings name capabilities (not explanations like "why_it_matters")? + Do headings match UI labels, commands, or mental models? + Are headings scannable in isolation? + Is H3 count ≤ 4 (typical ≤ 2)? + Are minor subtopics H4 instead of H3? + No H5/H6 used? + No orphan headings (each followed by ≥2 sentences or a list)? + + + + Does it start with the default path? + Are modes/levels/configuration after baseline usage? + Is troubleshooting optional and last (if present)? + + + + Neutral, direct, predictable tone? + No hype, jokes, or clever phrasing? + Short sentences, one idea each? + Active voice, concrete verbs? + No banned words (seamlessly, comprehensive, powerful, etc.)? + No vague verbs (handle, manage, process)? + No softening language (might try to, could potentially)? + + + + Are risks, costs, and irreversible actions explicit? + No apologizing for tradeoffs? + Errors state: what failed, why, one next step? + + + + Screenshots only for complex states or decision points? + Screenshot count ≤1 per section, ≤3 per page? + Alt text describes action/outcome (not UI chrome)? + Each screenshot has a "why this matters" caption? + Width is 600 (unless smaller improves readability)? + + + + Does the page explain why this exists (if non-obvious)? + Does it show how to use it? + Does it document decisions the user must make? + Does it cover known failure modes (if any exist)? + No UI narration that lacks decisions/implications? + + + + + + + + + For fast "cleanup this" requests, run abbreviated checks: + + First section shows behavior (not concept)? + Headings name capabilities? + 10-second scan test passes? + No banned words or UI narration? + ToC noise under control (H3 ≤ 4)? + + + diff --git a/.roomodes b/.roomodes index 8a420842..abc63d79 100644 --- a/.roomodes +++ b/.roomodes @@ -18,28 +18,33 @@ customModes: - slug: documentation-writer name: 📖 Documentation Writer roleDefinition: |- - You are Roo Code, a documentation specialist who writes only what matters. + You are Roo Code, a documentation specialist who sounds like a careful engineering teammate. + Calm, precise, focused on what will happen next. The goal is clarity and trust, not personality. + Core behaviors: - - 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). + - No fixed skeleton. Answer only what applies: capability, usage, choices, failures, deeper links. + - Front-load behavior: show what the feature does first, context follows. + - Headings name capabilities, not explanations. Match UI labels or commands. + - Neutral, direct tone. No hype, jokes, or clever phrasing. + - Short sentences, active voice, concrete verbs. + - Be explicit about risks. Do not apologize for tradeoffs. + - Progressive disclosure: default path first, then variations, troubleshooting last (if needed). + - Minimal ToC noise: H2 for sections; H3 only for jump-worthy anchors (max 4). + - Optimize for a reader skimming at 10 seconds. If the page reads like a form, it failed. + - Enforce .roo/rules-documentation-writer/ policies. whenToUse: |- - Use this mode to create or refine technical docs (.md/.mdx) with an explanatory, value-first approach and a clean, minimal ToC. + Use this mode to create, refine, or audit technical docs (.md/.mdx) optimized for reader momentum. Triggers: - - 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 + - "cleanup this section", "review this page", "audit this doc", "what's wrong with this" + - Pages that feel padded with mandatory sections that add no value + - Headings that describe intent abstractly instead of naming capabilities + - Need to front-load concrete behavior instead of conceptual framing + - Requests to optimize for 10-second scanning + - Pages with noisy ToCs or overuse of H3s description: Creates and maintains Roo technical docs. groups: - read - command - - - edit - - fileRegex: (\.(md|mdx)$|sidebars\.ts$|docusaurus\.config\.ts$) - description: Documentation files and sidebar configuration - mcp + - edit source: project diff --git a/docs/update-notes/index.md b/docs/update-notes/index.md index 10c25f3b..f66ab6c7 100644 --- a/docs/update-notes/index.md +++ b/docs/update-notes/index.md @@ -21,6 +21,12 @@ If you want to live on the edge and try things out before it's released, we have --- +### Version 3.46 + +- [3.46.0](/update-notes/v3.46.0) (2026-01-30) + +--- + ### Version 3.45 - [3.45.0](/update-notes/v3.45.0) (2026-01-28) diff --git a/docs/update-notes/v3.46.0.mdx b/docs/update-notes/v3.46.0.mdx new file mode 100644 index 00000000..99bb0169 --- /dev/null +++ b/docs/update-notes/v3.46.0.mdx @@ -0,0 +1,43 @@ +--- +description: This release adds parallel tool calling, overhauls file reading and terminal output handling, begins a shift toward the AI SDK, and adds a Settings UI for managing Skills. +keywords: + - roo code 3.46.0 + - new features + - bug fixes +image: /img/v3.46.0/v3.46.0.png +--- + +# Roo Code 3.46.0 Release Notes (2026-01-30) + +This is a BIG UPDATE! This release adds parallel tool calling, overhauls how Roo reads files and handles terminal output, and begins a major refactor to use the AI SDK at Roo's core for much better reliability. Together, these changes shift how Roo manages context and executes multi-step workflows in a serious way! Oh, and we also added a UI to manage your skills!! + +Roo Code v3.46.0 Release + +## Parallel tool calling + +Roo can now run multiple tools in one response when the workflow benefits from it. This gives the model more freedom to batch independent steps (reads, searches, edits, etc.) instead of making a separate API call for each tool. This reduces back-and-forth turns on multi-step tasks where Roo needs several independent tool calls before it can propose or apply a change. ([#11031](https://github.com/RooCodeInc/Roo-Code/pull/11031), [#11046](https://github.com/RooCodeInc/Roo-Code/pull/11046)) + +## Total read_file tool overhaul + +Roo now caps file reads by default (2000 lines) to avoid context overflows, and it can page through larger files as needed. When Roo needs context around a specific line (for example, a stack trace points at line 42), it can also request the *entire* containing function or class instead of an arbitrary “lines 40–60” slice. Under the hood, `read_file` now has two explicit modes: **slice** (`offset`/`limit`) for chunked reads, and **indentation** (anchored on a target line) for semantic extraction. (thanks pwilkin!) ([#10981](https://github.com/RooCodeInc/Roo-Code/pull/10981)) + +## Terminal handling overhaul + +When a command produces a lot of output, Roo now caps how much of that output it includes in the model’s context. The omitted portion is saved as an artifact. Roo can then page through the full output or search it on demand, so large builds and test runs stay debuggable without stuffing the entire log into every request. ([#10944](https://github.com/RooCodeInc/Roo-Code/pull/10944), [#11056](https://github.com/RooCodeInc/Roo-Code/pull/11056)) + +## Skills management in Settings + +You can now create, edit, and delete Skills from the Settings panel, with inline validation and delete confirmation. Editing a skill opens the `SKILL.md` file in VS Code. Skills are still stored as files on disk, but this makes routine maintenance faster—especially when you keep both **Global** skills and **Project** skills. (thanks SannidhyaSah!) ([#10844](https://github.com/RooCodeInc/Roo-Code/pull/10844)) + +## Provider migration to AI SDK + +We’ve started migrating providers toward a shared Vercel AI SDK foundation, so streaming, tool calling, and structured outputs behave more consistently across providers. In this release, that migration includes shared AI SDK utilities plus provider moves for Moonshot/OpenAI-compatible, DeepSeek, Cerebras, Groq, and Fireworks, and it also improves how provider errors (like rate limits) surface. ([#11047](https://github.com/RooCodeInc/Roo-Code/pull/11047), [#11063](https://github.com/RooCodeInc/Roo-Code/pull/11063), [#11079](https://github.com/RooCodeInc/Roo-Code/pull/11079), [#11086](https://github.com/RooCodeInc/Roo-Code/pull/11086), [#11088](https://github.com/RooCodeInc/Roo-Code/pull/11088), [#11118](https://github.com/RooCodeInc/Roo-Code/pull/11118)) + +## Boring stuff + +* The collapsed task header’s context percentage now reflects actual input usage (accounting for reserved output tokens), so it’s a more reliable indicator of how close you are to the context limit. ([#11034](https://github.com/RooCodeInc/Roo-Code/pull/11034), [#11054](https://github.com/RooCodeInc/Roo-Code/pull/11054)) +* Improves webview UI responsiveness by enabling React Compiler optimizations, reducing unnecessary re-renders without requiring manual memoization. (thanks In-line!) ([#9565](https://github.com/RooCodeInc/Roo-Code/pull/9565)) +* Adds `pnpm serve` / `pnpm serve:rebuild` commands to build and run the Roo Code extension in a web-based VS Code environment (via code-server), making it easier for maintainers and contributors to reproduce and validate web-specific behavior and ship fixes more reliably. ([#10964](https://github.com/RooCodeInc/Roo-Code/pull/10964)) +* Keeps the Roo Code web apps up to date with the latest Next.js release and related dependency/config updates, which helps reduce build and lint friction and improves compatibility/performance for the website and eval tooling. ([#11108](https://github.com/RooCodeInc/Roo-Code/pull/11108)) +* Improves the Roo Code website header navigation dropdowns by switching to the shadcn/Radix Navigation Menu component, giving smoother open/close animations, more reliable keyboard navigation, and more stable dropdown sizing during transitions. ([#11117](https://github.com/RooCodeInc/Roo-Code/pull/11117)) +* Replaces the legacy instruction-loading flow with a unified `skill` tool system, making it easier for Roo to load specialized instructions (like creating MCP servers or custom modes) on demand; also removes the old MCP “Enable MCP Server Creation” toggle. ([#11084](https://github.com/RooCodeInc/Roo-Code/pull/11084)) diff --git a/sidebars.ts b/sidebars.ts index 6f760bf9..56642b07 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -167,16 +167,21 @@ const sidebars: SidebarsConfig = { })), ], }, - { - type: "category", - label: "Extension Release Notes", - items: [ - "update-notes/index", { type: "category", - label: "3.45", - items: [{ type: "doc", id: "update-notes/v3.45.0", label: "3.45.0" }], - }, + label: "Extension Release Notes", + items: [ + "update-notes/index", + { + type: "category", + label: "3.46", + items: [{ type: "doc", id: "update-notes/v3.46.0", label: "3.46.0" }], + }, + { + type: "category", + label: "3.45", + items: [{ type: "doc", id: "update-notes/v3.45.0", label: "3.45.0" }], + }, { type: "category", label: "3.44", diff --git a/static/img/v3.46.0/v3.46.0.png b/static/img/v3.46.0/v3.46.0.png new file mode 100644 index 00000000..10aa0cf2 Binary files /dev/null and b/static/img/v3.46.0/v3.46.0.png differ