# Editing & Maintaining Prompts

This guide explains how to create, edit, version, and maintain prompts in [PromptOwl](https://promptowl.ai) for enterprise users.

---

## Overview

Prompts are the core building blocks of your AI workflows in PromptOwl. This guide covers:

- Creating new prompts
- Understanding prompt types (Simple, Sequential, Supervisor)
- Working with blocks and variations
- Managing variables
- Configuring AI models
- Version control and publishing

---

## Creating a New Prompt

### Starting a New Prompt

1. Click the **+ New** button on the Dashboard
2. Or navigate directly to **Create Prompt** from the sidebar


### Basic Prompt Information

Fill in the foundational details:

| Field | Description | Required |
|-------|-------------|----------|
| **Prompt Name** | A descriptive name for your prompt | Yes |
| **Description** | Brief explanation of what the prompt does | No |
| **Tags** | Keywords for organization and search | No |


---

## Understanding Prompt Types

PromptOwl supports three types of prompts to handle different complexity levels:

### Simple Prompt (Default)

Best for straightforward AI interactions with a single system context.

**Use cases:**
- Question answering
- Content generation
- Simple analysis tasks

**Structure:**
- One system context
- Direct user interaction
- Optional RAG (document retrieval)


---

### Sequential Prompt

Best for multi-step workflows where each step builds on the previous.

**Use cases:**
- Multi-stage content creation (research → draft → polish)
- Data processing pipelines
- Complex analysis with multiple phases

**Structure:**
- Multiple blocks executed in order
- Each block can use a different AI model
- Output from one block can feed into the next


---

### Supervisor Prompt

Best for complex tasks requiring multiple specialized AI agents.

**Use cases:**
- Multi-agent systems
- Tasks requiring different expertise
- Complex decision-making workflows

**Structure:**
- One supervisor block orchestrates the workflow
- Multiple agent blocks with specialized roles
- Supervisor decides which agents to invoke


---

## Working with Blocks

Blocks are the building units of Sequential and Supervisor prompts.

### Adding a Block

1. Click **Add Block** at the bottom of the blocks list
2. Enter a block name (e.g., "Research", "Summarize", "Format")
3. Configure the block settings


### Block Configuration Options

Each block has several configurable options:

| Setting | Description |
|---------|-------------|
| **Block Name** | Descriptive name for this step |
| **Prompt Source** | "Inline" (write here) or "Use Existing" (reference another prompt) |
| **AI Model** | Select the model for this block |
| **Tools** | Enable tools available to this block |
| **Dataset** | Connect documents for RAG |
| **Variables** | Map variables specific to this block |
| **Human Message** | Optional message shown between blocks |


### Using Existing Prompts in Blocks

To reuse an existing prompt within a block:

1. Set **Prompt Source** to "Use Existing"
2. Click **Select Prompt**
3. Browse and select the prompt to reference
4. Choose the version to use
5. Map any required variables


---

## Working with Variations

Variations allow you to test different prompt versions within the same block.

### Creating a Variation

1. Click the **+** button next to the variations tabs
2. Enter the variation text
3. Optionally name the variation


### Switching Between Variations

Click on the variation tab to switch the active version. The active variation is used when:
- Previewing the prompt
- Publishing to production
- Running evaluations

### Best Practices for Variations

- Use variations for A/B testing different phrasings
- Keep track of which variation performs best
- Document why each variation was created

---

## Managing Variables

Variables make your prompts dynamic and reusable.

### Adding a Variable

1. Click **Add Variable** in the Variables section
2. Enter the variable name (e.g., `company_name`, `tone`)
3. Set a default value (optional)
4. Check "Show as question" if users should provide this value


### Using Variables in Prompts

Insert variables using curly braces: ``\{variable_name\}``

**Example:**
```
You are a helpful assistant for `{company_name}`.
Please respond in a `{tone}` tone.
```

### Connecting Variables to Documents

To connect a variable to a document or folder:

1. Click **Connect Data** next to the variable
2. Browse your Data Room
3. Select a document or folder
4. The document content will be injected at runtime


### Variable Types

| Type | Format | Description |
|------|--------|-------------|
| **Text** | ``\{variable_name\}`` | Simple text replacement |
| **Document** | `artifact-`\{id\}`` | Single document content |
| **Folder** | `folder-`\{id\}`` | All documents in folder |
| **Block Output** | `\{\{block-key\}\}` | Output from previous block (Sequential/Supervisor) |

---

## Configuring AI Models

### Setting the Default Model

1. Click on the **Model** dropdown in the settings panel
2. Select your preferred AI provider:
   - OpenAI (GPT-4, GPT-4 Turbo, etc.)
   - Anthropic (Claude 3 Opus, Sonnet, Haiku)
   - Google (Gemini Pro, Gemini Ultra)
   - Groq (Llama, Mixtral)
3. Choose the specific model version


### Model Settings

Fine-tune model behavior with these settings:

| Setting | Description | Range |
|---------|-------------|-------|
| **Temperature** | Controls randomness (lower = more focused) | 0 - 2 |
| **Max Tokens** | Maximum response length | Varies by model |
| **Top P** | Nucleus sampling threshold | 0 - 1 |


### Per-Block Model Configuration

In Sequential and Supervisor prompts, each block can use a different model:

1. Expand the block settings
2. Toggle "Override default model"
3. Select the model for this block
4. Adjust settings as needed

---

## Version Control

PromptOwl automatically tracks all changes to your prompts.

### Understanding Versions

- **Draft Version** - Work in progress, not visible to users
- **Production Version** - The active version users interact with
- **Version History** - Complete record of all changes

### Viewing Version History

1. Open a prompt in edit mode
2. Click the **Versions** panel on the right
3. Browse all previous versions with:
   - Version number
   - Date created
   - Who created it
   - Change notes


### Saving a Draft

Click **Save** to create a new draft version without publishing. This allows you to:
- Work on changes over multiple sessions
- Test changes before going live
- Collaborate with team members on updates

### Publishing a Version

To make your changes live:

1. Click **Publish**
2. Add change notes describing what's different
3. Confirm the publication

The new version becomes the production version immediately.


### Restoring a Previous Version

To revert to an earlier version:

1. Open the Versions panel
2. Find the version you want to restore
3. Click **Publish** on that version
4. Confirm the restoration

> **Note:** This creates a new version based on the old one rather than deleting recent versions.

---

## Testing Your Prompt

### Preview Mode

Test your prompt without affecting production:

1. Click **Preview** in the editor
2. Enter test values for variables
3. Send test messages
4. Review the responses


### Best Practices for Testing

- Test with various input scenarios
- Try edge cases and unusual requests
- Verify variable substitution works correctly
- Check that document retrieval returns relevant content

---

## Prompt Settings

### General Settings

| Setting | Description |
|---------|-------------|
| **Enable Memory** | Remember conversation history |
| **Enable Citations** | Show source references for RAG |
| **Enable Tools** | Allow AI to use connected tools |

### Display Settings

| Setting | Description |
|---------|-------------|
| **Show in Sidebar** | Display prompt in user sidebar |
| **Featured** | Highlight on dashboard |
| **Custom Avatar** | Set a prompt icon |


---

## Sharing and Permissions

### Sharing with Individuals

1. Click the **Share** button
2. Enter email addresses
3. Select permission level (View, Edit)
4. Click **Share**

### Sharing with Teams

1. Click **Share**
2. Check "Share with team"
3. Select the team
4. Click **Share**


---

## Maintenance Best Practices

### Regular Reviews

- Review prompt performance monthly
- Check annotation feedback for improvement areas
- Update prompts when AI models improve

### Documentation

- Use descriptive names and descriptions
- Add change notes when publishing
- Tag prompts for easy organization

### Version Management

- Keep production versions stable
- Use drafts for experimental changes
- Document major changes in version notes

---

## Troubleshooting

### Prompt not responding as expected
1. Check variable values are correct
2. Verify the model settings
3. Review the system context for clarity
4. Test with simpler inputs first

### Variables not being replaced
1. Ensure variable names match exactly (case-sensitive)
2. Check for typos in ``\{variable_name\}`` syntax
3. Verify variables have values assigned

### Sequential blocks not passing data
1. Use `\{\{block-key\}\}` syntax to reference previous outputs
2. Verify block keys are correct
3. Check that previous blocks are generating output

### Model errors
1. Verify your API keys are configured
2. Check if the model is deprecated (warning will show)
3. Try a different model to isolate the issue

---

## Related Guides

- [Adding and Managing Users](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/adding-managing-users)
- [Adding and Organizing Documents](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/adding-organizing-documents)
- [Reviewing and Managing Annotations](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/reviewing-managing-annotations)