Skip to content

Commit cee3bc3

Browse files
hannesrudolphhannesrudolph
committed
feat: enhance documentation validation workflows with mandatory checks and enforcement rules
1 parent d315183 commit cee3bc3

File tree

3 files changed

+441
-80
lines changed

3 files changed

+441
-80
lines changed

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

Lines changed: 94 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,41 @@
1313
</discovery_principle>
1414

1515
<content_validation_principle>
16-
<rule>Before making any documentation changes, validate that the content is not redundant and maintains cohesion with existing documentation.</rule>
17-
<redundancy_check>
18-
<step>Use codebase_search to find similar content across all documentation</step>
19-
<step>Search for key terms and concepts from the requested changes</step>
20-
<step>Identify if the information already exists elsewhere</step>
21-
<step>If similar content exists, determine if this is an update, consolidation, or truly new content</step>
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>
2237
</redundancy_check>
23-
<cohesion_validation>
24-
<step>Check for contradictions with existing documentation</step>
25-
<step>Verify that new content aligns with established terminology and concepts</step>
26-
<step>Ensure cross-references are accurate and bidirectional where appropriate</step>
27-
<step>Validate that the change enhances rather than fragments the documentation flow</step>
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>
2844
</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>
2951
</content_validation_principle>
3052

3153
<core_principles>
@@ -95,40 +117,76 @@
95117
</before_writing_checklist>
96118

97119
<content_change_workflow>
98-
<phase name="analysis">
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">
99126
<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>
100128
<steps>
101-
<step>Identify the scope and purpose of the requested change</step>
102-
<step>List key concepts, terms, and topics involved</step>
103-
<step>Determine which documents might be affected</step>
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>
104133
</steps>
105134
</phase>
106-
<phase name="discovery">
107-
<description>Search for existing related content</description>
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>
108139
<steps>
109-
<step>Use codebase_search with key terms from the request</step>
110-
<step>Read all potentially related documentation sections</step>
111-
<step>Create a mental map of where information currently lives</step>
112-
<step>Identify any gaps, overlaps, or contradictions</step>
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>
113150
</steps>
114151
</phase>
115-
<phase name="validation">
116-
<description>Validate the change against existing content</description>
117-
<questions>
118-
<question>Does this information already exist elsewhere?</question>
119-
<question>If yes, should we update the existing location or consolidate?</question>
120-
<question>Will this change create any contradictions?</question>
121-
<question>Are all cross-references still valid?</question>
122-
<question>Does this enhance the documentation flow or fragment it?</question>
123-
</questions>
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>
124169
</phase>
125-
<phase name="implementation">
126-
<description>Apply changes with cohesion in mind</description>
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>
127174
<steps>
128-
<step>If updating existing content, preserve valuable context</step>
129-
<step>If adding new content, ensure it links appropriately to related topics</step>
130-
<step>Update any affected cross-references in other documents</step>
131-
<step>Maintain consistent terminology throughout</step>
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>
132190
</steps>
133191
</phase>
134192
</content_change_workflow>

0 commit comments

Comments
 (0)