Managing AI Prompts
This guide covers how administrators configure and manage the AI prompts that power the risk assessment pipeline. Prompt management is restricted to users with Admin role.Admin Access Required: All prompt management features require administrator privileges. Regular users cannot view or edit prompts.
Overview
AI prompts define how the system analyzes business documents and generates risk assessments. The platform uses prompts across 7 risk analysis sections:- Parser - Extracts structured data from PDFs
- Gap Detection - Identifies missing information
- Risk Analysis - Evaluates risks for each category
- Recommendations - Generates actionable advice
- Report Generation - Creates final assessment reports
- Quality Assurance - Validates analysis outputs
- Summarization - Produces executive summaries
Accessing Prompt Manager
Filtering and Searching Prompts
Use the toolbar filters to find specific prompts:Available Filters
| Filter | Options | Purpose |
|---|---|---|
| Section | Parser, Gap Detection, Risk Analysis, etc. | Filter by analysis stage |
| Status | Active, Inactive, All | Show only deployed or draft prompts |
| Tags | Multiple selection | Filter by category tags |
| Search | Text input | Search by name or content |
| Route | API endpoint paths | Filter by routing configuration |
Creating a New Prompt
You are an expert agricultural risk analyst specializing in
evaluating market risks for small and medium enterprises in
East Africa. Your analysis should be thorough, data-driven,
and actionable for non-technical stakeholders.
{{category_1}}, {{category_2}}, etc. - Individual category names{{categories}} - Comma-separated list of all categoriesAnalyze the following {{category_1}} risks for this agricultural
business. Consider:
1. Historical market volatility
2. Supply chain dependencies
3. Price fluctuation patterns
4. Competition landscape
Provide a risk score (0-100) and detailed evidence for your assessment.
Variable Replacement: Variables are automatically replaced at runtime with actual category names and data from the current assessment.
agriculture, sme, detailed-analysis{
"riskScore": 0-100,
"level": "LOW|MODERATE|HIGH|CRITICAL",
"evidence": "string",
"recommendations": ["string"]
}
Single Active Prompt Rule: Only one prompt per section should be active at a time. Activating a new prompt may automatically deactivate others in the same section.
Editing Existing Prompts
Preview Prompt Outputs
The Preview panel lets you test prompts with real AI before deploying.Version Control and History
Viewing Change History
Click the “History” tab in the prompt editor to see:- Version timeline: Chronological list of all versions
- Author: Who made each change
- Timestamp: When the change was made
- Change summary: Auto-generated diff highlights
Comparing Versions
Expand any version to see: Field-level diffs:- Added content in green
- Removed content in red
- Unchanged fields collapsed
- System prompt modifications
- User template updates
- Category/tag additions or removals
- Status changes (active ↔ inactive)
Reverting to Previous Version
- Navigate to the History tab
- Find the desired version
- Click “View This Version”
- Review the historical prompt content
- Copy content to current version if needed
No Direct Rollback: The system doesn’t support automatic rollback. To restore an old version, copy its content into the current editor and save as a new version.
Commenting and Collaboration
Adding Comments
Click the “Comments” tab in the prompt editor:- Type your comment in the text box
- Mention specific concerns or suggestions
- Click “Add Comment”
- Comment appears with your email and timestamp
Threaded Discussions
Comments support threading:- Click “Reply” on any comment to create a thread
- Replies are indented under parent comments
- Track decision rationale and team discussions
Use Cases for Comments
- Review requests: “@team please review this market risk prompt”
- Change rationale: “Updated tone to be less technical per user feedback”
- TODO tracking: “Need to add climate considerations to categories”
- Version notes: “v4: Fixed JSON output format to match API spec”
Import and Export
Exporting Prompts
- Click “Export” in the top toolbar
- Choose format:
- JSON: Full prompt data with metadata
- CSV: Spreadsheet format for bulk review
- File downloads with timestamp:
prompts-2026-03-04.json
- All prompt fields
- Current version only
- Active/inactive status
- Categories and tags
Importing Prompts
- Click “Import” in the toolbar
- Upload a JSON file (exported from this system)
- Select import mode:
- Create New: Skip existing prompts, create new ones only
- Upsert: Update existing prompts, create new ones
- Review import summary
- Confirm to proceed
Toggling Active Status
Quickly enable or disable prompts:From the Prompt List
- Locate the prompt card
- Click the toggle icon (⚡)
- Status badge updates immediately
- Active prompts show green “Active” badge
- Inactive prompts show gray “Inactive” badge
From the Editor
Use the Active/Inactive switch at the bottom of the form.Best Practices
When to Deactivate
When to Deactivate
- Testing new prompts before production deployment
- Temporarily disabling problematic prompts
- Archiving outdated prompts without deleting
- A/B testing different prompt versions
Single Active Prompt
Single Active Prompt
Ensure only one prompt per section is active:
- Prevents conflicting analysis logic
- Maintains consistent user experience
- System may auto-deactivate others when you activate a new one
Best Practices
Writing Effective Prompts
Writing Effective Prompts
System Prompts:
- Be specific about expertise domain
- Define output expectations clearly
- Include relevant context about CGIAR mission
- Set appropriate tone for target audience
- Use clear, structured questions
- Leverage variable injection for dynamic content
- Specify output format requirements
- Include evaluation criteria
Version Management
Version Management
- Save frequently to create restore points
- Use comments to document why changes were made
- Test with Preview before activating
- Keep descriptive prompt names
- Review change history before major updates
Collaboration Workflow
Collaboration Workflow
- Draft new prompt as Inactive
- Share prompt ID with team via comments
- Collect feedback in comment threads
- Iterate based on preview outputs
- Activate only after team approval
- Monitor assessment results post-deployment
Troubleshooting
Preview Keeps Failing
Preview Keeps Failing
- Check that both System and User prompts are filled
- Verify variable syntax:
{{category_1}}not{category_1} - Ensure no special characters in JSON output format
- Try shorter prompts - very long prompts may timeout
- Check admin console for error messages
Prompt Not Appearing in Analysis
Prompt Not Appearing in Analysis
- Verify the prompt is marked Active (green badge)
- Check that Section matches the analysis stage
- Ensure no other prompt in same section is active
- Wait 1-2 minutes for cache refresh
- Try creating a new test assessment
Can't Save Changes
Can't Save Changes
- Check for validation errors in red text
- Ensure required fields (Name, Section, System/User prompts) are filled
- Verify you have admin permissions
- Try refreshing the page if session expired
- Check browser console for JavaScript errors