Skip to content

Commit 2fdbf84

Browse files
hannesrudolphhannesrudolph
authored
feat: add writing style and Docusaurus conventions guides; update doc… (#283)
* feat: add writing style and Docusaurus conventions guides; update documentation writer mode * feat: enhance documentation validation workflows with mandatory checks and enforcement rules
1 parent 1128146 commit 2fdbf84

File tree

6 files changed

+742
-179
lines changed

6 files changed

+742
-179
lines changed

‎.roo/rules-docs/1_writing_style.xml‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

‎.roo/rules-docs/2_docusaurus_conventions.xml‎

Lines changed: 0 additions & 89 deletions
This file was deleted.

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

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
<writing_style_guide>
2+
<overview>
3+
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.
4+
</overview>
5+
6+
<discovery_principle>
7+
<rule>Before writing or editing documentation, always explore existing documentation to understand established patterns, style, and structure.</rule>
8+
<steps>
9+
<step>Use list_files to explore the documentation structure</step>
10+
<step>Read similar existing documents to understand the style</step>
11+
<step>Follow established patterns rather than imposing new ones</step>
12+
</steps>
13+
</discovery_principle>
14+
15+
<content_validation_principle>
16+
<rule>MANDATORY: Before making ANY changes to existing documentation files, you MUST complete the redundancy validation workflow. This is NOT optional.</rule>
17+
<enforcement>
18+
<requirement>You CANNOT proceed with edits until validation is complete</requirement>
19+
<requirement>You MUST document validation results before making changes</requirement>
20+
<requirement>Skipping validation steps will result in task rejection</requirement>
21+
</enforcement>
22+
<redundancy_check priority="CRITICAL">
23+
<mandatory_step order="1">Use codebase_search to find ALL mentions of the topic across documentation</mandatory_step>
24+
<mandatory_step order="2">Search for multiple variations of key terms (e.g., if editing "authentication", also search "auth", "login", "security", "credentials")</mandatory_step>
25+
<mandatory_step order="3">Read and analyze EVERY discovered location thoroughly</mandatory_step>
26+
<mandatory_step order="4">Create a validation report listing:
27+
- All locations where similar content exists
28+
- The current state of each location
29+
- Potential conflicts or duplications
30+
- Recommendation for how to proceed
31+
</mandatory_step>
32+
<mandatory_step order="5">If similar content exists, you MUST determine:
33+
- Is this an update to existing content? (proceed to that location)
34+
- Is this a consolidation opportunity? (merge content)
35+
- Is this truly new, non-redundant content? (proceed with caution)
36+
</mandatory_step>
37+
</redundancy_check>
38+
<cohesion_validation priority="CRITICAL">
39+
<mandatory_step>Check for contradictions with existing documentation</mandatory_step>
40+
<mandatory_step>Verify that new content aligns with established terminology and concepts</mandatory_step>
41+
<mandatory_step>Ensure cross-references are accurate and bidirectional where appropriate</mandatory_step>
42+
<mandatory_step>Validate that the change enhances rather than fragments the documentation flow</mandatory_step>
43+
<mandatory_step>Document how the change improves overall documentation cohesion</mandatory_step>
44+
</cohesion_validation>
45+
<validation_gate>
46+
<rule>You MUST use ask_followup_question to confirm validation results with the user BEFORE proceeding with any edits</rule>
47+
<template>
48+
"I've completed the mandatory redundancy validation. Here's what I found: [validation results]. Based on this analysis, I recommend: [recommendation]. Should I proceed with this approach?"
49+
</template>
50+
</validation_gate>
51+
</content_validation_principle>
52+
53+
<core_principles>
54+
<principle name="directness">
55+
<rule>Start with the most important information. No filler introductions.</rule>
56+
<bad>In this guide, we will explore how to configure the tool.</bad>
57+
<good>To configure the tool, open...</good>
58+
</principle>
59+
<principle name="brevity">
60+
<rule>Use short sentences. Cut unnecessary words. If it doesn't add value, remove it.</rule>
61+
</principle>
62+
<principle name="utility">
63+
<rule>Focus on what the user can do and why it matters. Provide actionable steps.</rule>
64+
</principle>
65+
<principle name="consistency">
66+
<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>
67+
<discovery_approach>
68+
<step>Read the entire document first to understand its current style</step>
69+
<step>Identify patterns in headings, formatting, and tone</step>
70+
<step>Match the existing style in your edits</step>
71+
</discovery_approach>
72+
</principle>
73+
</core_principles>
74+
75+
<banned_language>
76+
<description>Avoid marketing jargon, buzzwords, and clichés. These words are ambiguous and reduce signal.</description>
77+
<discovery_note>When editing existing documentation, check if any of these words are already used and maintain consistency with the existing approach.</discovery_note>
78+
<words>
79+
<word>seamlessly</word>
80+
<word>comprehensive</word>
81+
<word>enhanced</word>
82+
<word>streamlined</word>
83+
<word>powerful</word>
84+
<word>improved</word>
85+
<word>intuitive</word>
86+
<word>state-of-the-art</word>
87+
<word>revolutionary</word>
88+
<word>robust</word>
89+
<word>easily</word>
90+
<word>simply</word>
91+
</words>
92+
</banned_language>
93+
94+
<formatting>
95+
<guideline>Use structured headings, lists, and short paragraphs for scannability.</guideline>
96+
<guideline>Provide clear, copy-pasteable code snippets.</guideline>
97+
<guideline>Assume user familiarity with basic concepts. Do not over-explain.</guideline>
98+
<discovery_approach>
99+
<step>Before formatting new content, examine existing documentation for:
100+
- Heading hierarchy patterns (H1, H2, H3 usage)
101+
- List formatting preferences (bullets vs numbers)
102+
- Code block styling and language tags
103+
- Paragraph length and structure
104+
</step>
105+
<step>Match the discovered patterns to maintain consistency</step>
106+
</discovery_approach>
107+
</formatting>
108+
109+
<before_writing_checklist>
110+
<item>Have I explored the existing documentation structure?</item>
111+
<item>Have I read similar documents to understand the established style?</item>
112+
<item>Have I identified the patterns for paths, links, and references?</item>
113+
<item>Am I following discovered patterns rather than making assumptions?</item>
114+
<item>Have I searched for existing content that might overlap with my changes?</item>
115+
<item>Have I verified that my changes don't contradict existing documentation?</item>
116+
<item>Have I checked that cross-references will remain valid?</item>
117+
</before_writing_checklist>
118+
119+
<content_change_workflow>
120+
<mandatory_notice>
121+
<warning>This workflow is MANDATORY for ALL documentation changes. Each phase MUST be completed in order.</warning>
122+
<enforcement>Skipping any phase or step will invalidate the entire change request.</enforcement>
123+
</mandatory_notice>
124+
125+
<phase name="analysis" status="MANDATORY">
126+
<description>Analyze the requested change and its impact</description>
127+
<blocking_requirement>You CANNOT proceed to the next phase until ALL steps are complete</blocking_requirement>
128+
<steps>
129+
<step validation="required">Identify the scope and purpose of the requested change</step>
130+
<step validation="required">List ALL key concepts, terms, and their variations (e.g., "config" → "configuration", "setup", "settings")</step>
131+
<step validation="required">Determine which documents might be affected (use list_files to verify)</step>
132+
<step validation="required">Document your analysis results before proceeding</step>
133+
</steps>
134+
</phase>
135+
136+
<phase name="discovery" status="MANDATORY">
137+
<description>Search for ALL existing related content - this phase is NOT optional</description>
138+
<blocking_requirement>You MUST find and analyze ALL related content before proceeding</blocking_requirement>
139+
<steps>
140+
<step validation="required">Use codebase_search with the primary term from the request</step>
141+
<step validation="required">Use codebase_search with EACH variation of key terms identified in analysis</step>
142+
<step validation="required">Read ALL potentially related documentation sections in full</step>
143+
<step validation="required">Create a comprehensive map documenting:
144+
- Every location where related information exists
145+
- The specific content at each location
146+
- How each location relates to the requested change
147+
</step>
148+
<step validation="required">Identify any gaps, overlaps, or contradictions</step>
149+
<step validation="required">If you find existing content, you MUST read it completely before proceeding</step>
150+
</steps>
151+
</phase>
152+
153+
<phase name="validation" status="MANDATORY">
154+
<description>Validate the change against existing content - MUST be completed before ANY edits</description>
155+
<blocking_requirement>You MUST answer ALL questions and get user confirmation before implementation</blocking_requirement>
156+
<validation_checklist>
157+
<check mandatory="true">Does this exact information already exist elsewhere? (If yes, STOP and redirect to existing location)</check>
158+
<check mandatory="true">Does similar but incomplete information exist? (If yes, enhance existing rather than duplicate)</check>
159+
<check mandatory="true">Will this change create any contradictions with existing docs?</check>
160+
<check mandatory="true">Have you verified ALL cross-references will remain valid?</check>
161+
<check mandatory="true">Does this enhance the documentation flow or fragment it?</check>
162+
<check mandatory="true">Have you identified ALL files that need updates to maintain consistency?</check>
163+
</validation_checklist>
164+
<user_confirmation_required>
165+
<rule>You MUST use ask_followup_question to present validation findings and get approval</rule>
166+
<rule>Include specific file paths and line numbers in your validation report</rule>
167+
<rule>Provide clear recommendations based on your findings</rule>
168+
</user_confirmation_required>
169+
</phase>
170+
171+
<phase name="implementation" status="CONDITIONAL">
172+
<description>Apply changes ONLY after validation is approved by user</description>
173+
<blocking_requirement>You can ONLY enter this phase after user approves validation results</blocking_requirement>
174+
<steps>
175+
<step validation="required">If updating existing content, preserve ALL valuable context</step>
176+
<step validation="required">If adding new content, ensure it links appropriately to ALL related topics discovered in phase 2</step>
177+
<step validation="required">Update ALL affected cross-references in other documents</step>
178+
<step validation="required">Maintain consistent terminology throughout ALL affected files</step>
179+
<step validation="required">Verify no information is lost or contradicted by your changes</step>
180+
</steps>
181+
</phase>
182+
183+
<phase name="post_implementation_verification" status="MANDATORY">
184+
<description>Verify the changes maintain documentation integrity</description>
185+
<steps>
186+
<step validation="required">Re-run codebase_search to ensure no duplicates were created</step>
187+
<step validation="required">Verify all cross-references still work</step>
188+
<step validation="required">Confirm terminology remains consistent</step>
189+
<step validation="required">Document what was changed and why for future reference</step>
190+
</steps>
191+
</phase>
192+
</content_change_workflow>
193+
</writing_style_guide>

0 commit comments

Comments
 (0)