docs: Add prompt structure documentation to advanced usage sidebar

Author: hannesrudolph

docs/advanced-usage/prompt-structure.md

@@ -0,0 +1,89 @@
+# Prompt Structure
+
+This page explains the technical structure of prompts in Roo Code - how messages are constructed and sent to the Large Language Model (LLM).
+
+## Core Message Types
+
+Roo Code uses three primary message types when communicating with LLMs:
+
+- **System Prompt**: The initial instructions that define Roo's capabilities, persona, and operational rules
+- **User Messages**: Content sent by you (the user) to Roo
+- **Assistant Messages**: Responses generated by the LLM based on your requests
+
+Understanding these message types helps you work more effectively with Roo and can be valuable for troubleshooting or advanced customization.
+
+## System Prompt
+
+The system prompt is the foundation of Roo's behavior. It contains:
+
+- **Role Definition**: The core persona instructions based on the selected mode (Code, Ask, Debug, etc.)
+- **Tool Descriptions**: Detailed information about available tools, including parameters and examples
+- **Tool Use Guidelines**: Rules for how tools should be used (sequential execution, waiting for results)
+- **Capabilities**: Description of what Roo can do in the current environment
+- **Available Modes**: List of all available modes and their descriptions
+- **Operational Rules**: Critical guidelines for handling files, project structure, and user interaction
+- **System Information**: Details about your environment (OS, shell, working directory)
+- **Custom Instructions**: Your global and mode-specific customizations
+
+The system prompt is generated dynamically each time you interact with Roo, adapting to your current mode, available tools, and custom settings.
+
+### Custom System Prompts
+
+Advanced users can create custom system prompts for specific modes by placing a `.roo/system-prompt-<mode_slug>` file in their workspace. When present, Roo uses this file instead of generating the standard system prompt sections, allowing for complete customization of Roo's behavior in that mode.
+
+## User Messages
+
+User messages contain your direct inputs to Roo, plus additional contextual information:
+
+- **Your Query**: The text you type in the chat interface
+- **Images**: Any images you include in your message (for supported models)
+- **Environment Details**: Automatically appended information about your workspace state:
+  - Open files/tabs
+  - Cursor position
+  - Active terminals with output
+  - Recently modified files
+  - Current time and token/cost information
+  - Current mode
+  - File listing (on initial connection)
+
+This automatic context enrichment helps Roo understand your workspace without requiring you to explicitly describe it.
+
+## Assistant Messages
+
+Assistant messages are the LLM's responses, which may include:
+
+- **Text Responses**: Direct answers to your queries
+- **Thinking**: Internal reasoning process (visible when enabled)
+- **Tool Calls**: Requests to use specific tools like reading files or executing commands
+- **Tool Results**: The outcome of executed tools
+
+## Message Flow
+
+Here's how these components work together:
+
+1. **Initial Setup**: Roo generates the system prompt based on your selected mode and configuration
+2. **User Input**: You send a message, which is enriched with environment details
+3. **LLM Processing**: The LLM receives all previous messages plus your new input
+4. **Assistant Response**: The LLM generates a response, potentially using tools
+5. **Tool Execution**: If the LLM requests a tool, Roo executes it and provides the result
+6. **Conversation History**: All messages are maintained in a structured history for context
+
+## Technical Implementation
+
+Internally, Roo's prompt construction is handled by several components:
+
+- **System Prompt Generation**: The `SYSTEM_PROMPT` function in `src/core/prompts/system.ts` assembles the complete system prompt
+- **Section Generators**: Specialized functions create each section of the system prompt
+- **Message Transformation**: Provider-specific transformers convert Roo's internal message format to the format required by each LLM API
+- **Custom Prompt Loading**: The `loadSystemPromptFile` function checks for and processes custom system prompt files
+
+## Optimizing Your Interactions
+
+Understanding this structure can help you:
+
+- **Write Better Prompts**: Knowing what context Roo already has helps you avoid redundant information
+- **Troubleshoot Issues**: Understanding message flow helps identify where problems might occur
+- **Create Custom Modes**: With knowledge of the system prompt structure, you can create more effective custom modes
+- **Use Custom System Prompts**: Advanced users can create entirely custom system prompts for specialized use cases
+
+This technical foundation powers all of Roo's capabilities, enabling it to understand your requests and effectively utilize available tools to complete tasks.

sidebars.ts

@@ -68,6 +68,7 @@ const sidebars: SidebarsConfig = {
       label: 'Advanced Usage',
       items: [
         'advanced-usage/prompt-engineering',
+        'advanced-usage/prompt-structure',
         'advanced-usage/large-projects',
         'advanced-usage/rate-limits-costs',
         'advanced-usage/local-models',