docs: document process for adding new settings (#2552)

Add documentation explaining how to implement new settings in Roo Code,
using the command risk level feature as a practical example.

Signed-off-by: Eric Wheeler <[email protected]>
Co-authored-by: Eric Wheeler <[email protected]>

cline_docs/settings.md

@@ -183,39 +183,39 @@ These steps ensure that:
 
 To add a new configuration item to the system, the following changes are necessary:
 
-1. **Feature-Specific Class** (if applicable)
+1.  **Feature-Specific Class** (if applicable)
 
     - For settings that affect specific features (e.g., Terminal, Browser, etc.)
     - Add a static property to store the value
     - Add getter/setter methods to access and modify the value
 
-2. **Schema Definition**
+2.  **Schema Definition**
 
     - Add the item to globalSettingsSchema in schemas/index.ts
     - Add the item to globalSettingsRecord in schemas/index.ts
 
-3. **Type Definitions**
+3.  **Type Definitions**
 
     - Add the item to exports/types.ts
     - Add the item to exports/roo-code.d.ts
     - Add the item to shared/ExtensionMessage.ts
     - Add the item to shared/WebviewMessage.ts
 
-4. **UI Component**
+4.  **UI Component**
 
     - Create or update a component in webview-ui/src/components/settings/
     - Add appropriate slider/input controls with min/max/step values
     - Ensure the props are passed correctly to the component in SettingsView.tsx
     - Update the component's props interface to include the new settings
 
-5. **Translations**
+5.  **Translations**
 
     - Add label and description in webview-ui/src/i18n/locales/en/settings.json
     - Update all other languages
     - If any language content is changed, synchronize all other languages with that change
     - Translations must be performed within "translation" mode so change modes for that purpose
 
-6. **State Management**
+6.  **State Management**
 
     - Add the item to the destructuring in SettingsView.tsx
     - Add the item to the handleSubmit function in SettingsView.tsx
@@ -223,11 +223,11 @@ To add a new configuration item to the system, the following changes are necessa
     - Add the item to getState in ClineProvider.ts with appropriate default values
     - Add the item to the initialization in resolveWebviewView in ClineProvider.ts
 
-7. **Message Handling**
+7.  **Message Handling**
 
     - Add a case for the item in webviewMessageHandler.ts
 
-8. **Implementation-Specific Logic**
+8.  **Implementation-Specific Logic**
 
     - Implement any feature-specific behavior triggered by the setting
     - Examples:
@@ -235,7 +235,7 @@ To add a new configuration item to the system, the following changes are necessa
         - API configuration changes for provider settings
         - UI behavior modifications for display settings
 
-9. **Testing**
+9.  **Testing**
 
     - Add test cases for the new settings in appropriate test files
     - Verify settings persistence and state updates
@@ -305,40 +305,139 @@ To add a new configuration item to the system, the following changes are necessa
 
 11. **Debugging Settings Persistence Issues**
 
-    If a setting is not persisting across reload, check the following:
+        If a setting is not persisting across reload, check the following:
 
-    1. **Complete Chain of Persistence**:
+        1. **Complete Chain of Persistence**:
 
-        - Verify that the setting is added to all required locations:
-            - globalSettingsSchema and globalSettingsRecord in schemas/index.ts
-            - Initial state in ExtensionStateContextProvider
-            - getState method in ClineProvider.ts
-            - getStateToPostToWebview method in ClineProvider.ts
-            - resolveWebviewView method in ClineProvider.ts (if feature-specific)
-        - A break in any part of this chain can prevent persistence
+            - Verify that the setting is added to all required locations:
+                - globalSettingsSchema and globalSettingsRecord in schemas/index.ts
+                - Initial state in ExtensionStateContextProvider
+                - getState method in ClineProvider.ts
+                - getStateToPostToWebview method in ClineProvider.ts
+                - resolveWebviewView method in ClineProvider.ts (if feature-specific)
+            - A break in any part of this chain can prevent persistence
 
-    2. **Default Values Consistency**:
+        2. **Default Values Consistency**:
 
-        - Ensure default values are consistent across all locations
-        - Inconsistent defaults can cause unexpected behavior
+            - Ensure default values are consistent across all locations
+            - Inconsistent defaults can cause unexpected behavior
 
-    3. **Message Handling**:
+        3. **Message Handling**:
 
-        - Confirm the webviewMessageHandler.ts has a case for the setting
-        - Verify the message type matches what's sent from the UI
+            - Confirm the webviewMessageHandler.ts has a case for the setting
+            - Verify the message type matches what's sent from the UI
 
-    4. **UI Integration**:
+        4. **UI Integration**:
 
-        - Check that the setting is included in the handleSubmit function in SettingsView.tsx
-        - Ensure the UI component correctly updates the state
+            - Check that the setting is included in the handleSubmit function in SettingsView.tsx
+            - Ensure the UI component correctly updates the state
 
-    5. **Type Definitions**:
+        5. **Type Definitions**:
 
-        - Verify the setting is properly typed in all relevant interfaces
-        - Check for typos in property names across different files
+            - Verify the setting is properly typed in all relevant interfaces
+            - Check for typos in property names across different files
 
-    6. **Storage Mechanism**:
-        - For complex settings, ensure proper serialization/deserialization
-        - Check that the setting is being correctly stored in VSCode's globalState
+        6. **Storage Mechanism**:
+            - For complex settings, ensure proper serialization/deserialization
+            - Check that the setting is being correctly stored in VSCode's globalState
 
     These checks help identify and resolve common issues with settings persistence.
+
+12. **Advanced Troubleshooting: The Complete Settings Persistence Chain**
+
+Settings persistence requires a complete chain of state management across multiple components. Understanding this chain is critical for both humans and AI to effectively troubleshoot persistence issues:
+
+1. **Schema Definition (Entry Point)**:
+
+    - Settings must be properly defined in `globalSettingsSchema` and `globalSettingsRecord`
+    - Enum values should use proper zod schemas: `z.enum(["value1", "value2"])`
+    - Example:
+
+        ```typescript
+        // In schemas/index.ts
+        export const globalSettingsSchema = z.object({
+        	// Existing settings...
+        	commandRiskLevel: z.enum(["readOnly", "reversibleChanges", "complexChanges"]).optional(),
+        })
+
+        const globalSettingsRecord: GlobalSettingsRecord = {
+        	// Existing settings...
+        	commandRiskLevel: undefined,
+        }
+        ```
+
+2. **UI Component (User Interaction)**:
+
+    - Must use consistent components (Select vs. select) with other similar settings
+    - Must use `setCachedStateField` for state updates, not direct state setting
+    - Must generate the correct message type through `vscode.postMessage`
+    - Example:
+        ```tsx
+        // In a settings component
+        <Select value={commandRiskLevel} onValueChange={(value) => setCachedStateField("commandRiskLevel", value)}>
+        	<SelectTrigger className="w-full">
+        		<SelectValue placeholder={t("settings:common.select")} />
+        	</SelectTrigger>
+        	<SelectContent>
+        		<SelectGroup>
+        			<SelectItem value="readOnly">{t("label.readOnly")}</SelectItem>
+        			{/* Other options... */}
+        		</SelectGroup>
+        	</SelectContent>
+        </Select>
+        ```
+
+3. **Message Handler (State Saving)**:
+
+    - Must use correct message type in `webviewMessageHandler.ts`
+    - Must use `updateGlobalState` with properly typed values
+    - Must call `postStateToWebview` after updates
+    - Example:
+        ```typescript
+        // In webviewMessageHandler.ts
+        case "commandRiskLevel":
+          await updateGlobalState(
+            "commandRiskLevel",
+            (message.text ?? "readOnly") as "readOnly" | "reversibleChanges" | "complexChanges"
+          )
+          await provider.postStateToWebview()
+          break
+        ```
+
+4. **State Retrieval (Reading State)**:
+
+    - In `getState`, state must be properly retrieved from stateValues
+    - In `getStateToPostToWebview`, the setting must be in the destructured parameters
+    - The setting must be included in the return value
+    - Use `contextProxy.getGlobalState` for direct access when needed
+    - Example:
+
+        ```typescript
+        // In ClineProvider.ts getStateToPostToWebview
+        const {
+        	// Other state properties...
+        	commandRiskLevel,
+        } = await this.getState()
+
+        return {
+        	// Other state properties...
+        	commandRiskLevel: commandRiskLevel ?? "readOnly",
+        }
+        ```
+
+5. **Debugging Strategies**:
+
+    - **Follow the State Flow**: Watch the setting's value at each step in the chain
+    - **Type Safety**: Ensure the same type is used throughout the chain
+    - **Component Consistency**: Use the same pattern as other working settings
+    - **Check Return Values**: Ensure the setting is included in all return objects
+    - **State vs. Configuration**: Understand when to use state vs. VSCode configuration
+
+6. **Common Pitfalls**:
+    - **Type Mismatch**: Using string where an enum is expected
+    - **Chain Breaks**: Missing the setting in return objects
+    - **UI Inconsistency**: Using different component patterns
+    - **DefaultValue Issues**: Inconsistent default values across components
+    - **Missing Schema**: Not adding to schema or record definitions
+
+Remember: A break at ANY point in this chain can cause persistence failures. When troubleshooting, systematically check each link in the chain to identify where the issue occurs.