Quick Reference
| Property | Value |
|---|---|
| Domain | Prompts |
| FORGE Stage | 3 (Documentation) |
| Version | 1.0.0 |
| Primary Output | Refined Veritas-compliant prompts |
Use this agent when you need to:
- Improve the clarity and effectiveness of draft prompts
- Validate prompts against Veritas schema requirements
- Document variables and placeholders in existing prompts
- Calculate quality scores for prompt assessment
Core Capabilities
Prompt Optimization
Improves prompt clarity, specificity, and effectiveness using established engineering patterns
Schema Validation
Ensures prompts conform to Veritas JSON schema with complete metadata
Variable Documentation
Documents all placeholders, types, defaults, and usage requirements
Quality Scoring
Assesses prompts against clarity rubric (target: >0.8)
When to Use
Ideal Use Cases
Draft prompts need clarity improvements before production use
Existing prompts produce inconsistent or ambiguous outputs
Variables/placeholders lack documentation or type information
Prompts require Veritas schema validation and compliance
Quality metrics needed for prompt performance assessment
Not Recommended For
Usage Examples
- Code Review Prompt
- Incident Triage
- Documentation Task
Output Format
Veritas-Compliant Prompt Schema
Prompt Quality Rubric
The agent assesses prompts using a weighted scoring system:| Component | Weight | Criteria |
|---|---|---|
| Specificity | 25% | Clear, unambiguous instructions |
| Structure | 20% | Logical organization and flow |
| Variables | 20% | Well-defined, documented placeholders |
| Output Format | 20% | Clear output expectations |
| Context | 15% | Appropriate role/persona setting |
Improvement Patterns
Common prompt engineering patterns applied during refinement:Role Anchoring
Output Structuring
Example Injection
Constraint Setting
FORGE Gate Compliance
Entry Gates (Pre-conditions)
Entry Gates (Pre-conditions)
Before invoking this agent, ensure:
- Draft prompt provided: Raw prompt text to be refined
- Use case documented: Target application or workflow context
- Veritas schema available: Schema version for validation
- Output format specified: Expected response format (text/JSON/markdown)
Exit Gates (Post-conditions)
Exit Gates (Post-conditions)
This agent completes successfully when:
- Refined prompt delivered: Improved version with documented changes
- Schema validation passed: Full Veritas compliance confirmed
- Clarity score calculated: Score >0.8 achieved
- Variables documented: All placeholders have type/description/defaults
- Test cases defined: Coverage >80% of variable combinations
- Decision record logged: ADR format with refinement rationale
Decision Record Format
Decision Record Format
All significant refinement decisions are logged as:
Integration Points
Control Plane API
This agent does not directly interact with the Control Plane API - it operates on prompt assets managed in the Veritas repository.Veritas Prompt Library
Consumes:vrt-meta001: Meta-prompt template for prompt improvementvrt-clarity01: Clarity assessment criteria rubricvrt-schema01: Veritas schema validation rules
- Refined prompts in
veritas/agent-prompts/prompts/ - Status:
draft(requires manual review before production)
Repository Integration
- Primary:
so1-io/veritas- Veritas prompt library - Secondary:
so1-io/so1-agents- Agent prompt consumption
Related Agents
| Agent | Relationship | Integration Point |
|---|---|---|
| Chain Architect | Downstream | Receives refined prompts for multi-step chains |
| Fragment Curator | Peer | Provides reusable fragments during refinement |
| Factory Orchestrator | Upstream | Routes refinement requests and manages workflow |
| Documentation Agents | Consumer | Request prompt refinement for doc generation tasks |
Error Handling
Common Issues
Escalation Path
If the agent cannot complete refinement:- Log decision record with
status:blocked - Output partial refinement with clarity issues flagged
- Return control to Factory Orchestrator with blocker details
Success Metrics
| Metric | Target | Measurement |
|---|---|---|
| Clarity Score | >0.8 | Rubric-based weighted assessment |
| Schema Compliance | 100% | Veritas schema validation pass |
| Variable Coverage | 100% | All placeholders documented |
| Test Case Coverage | >80% | Tests per variable combination |
Source Files
View Agent Source
Maintained in
so1-agents repository under agents/prompts/prompt-refiner.md