MANDATORY PREPARATION
Invoke /agent-workflow — it contains workflow principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no workflow context exists yet, you MUST run /teach-maestro first.
This is the final quality pass. The workflow works — now make it excellent.
Refinement Checklist
Prompts
- Every prompt follows the 4-zone pattern (role, context, instructions, output)
- Output schemas are explicit and validated
- Negative instructions clarify what NOT to do
- No contradictory instructions
- Few-shot examples included for ambiguous tasks
- Chain-of-thought used for multi-step reasoning tasks
Tool Descriptions
- Every tool has a multi-line description: what, when to use, when NOT to use, returns
- Input parameters have descriptions and types
- Error responses are documented
- At least one example input/output in the description
Error Messages
- Error messages are specific (not "an error occurred")
- Error messages suggest corrective action
- Errors include context (what was being attempted)
- Errors are structured (code + message + details)
Logging
- Every model call is logged (input tokens, output tokens, latency, cost)
- Tool calls are logged with inputs and outputs
- Errors are logged with full context
- PII is redacted from logs
- Workflow ID traces through all log entries
Configuration
- All magic numbers are named constants
- Environment-specific values are in config, not code
- Defaults are sensible — config is for overrides
- Cost ceilings are set
- Timeout values are set for all external calls
Output
For each checklist item that fails, provide:
- What's wrong (specific finding)
- Where it is (file, line, or component)
- How to fix it (concrete suggestion)
- Priority (critical / important / nice-to-have)
Priority Matrix
| Priority | Criteria | Maestro Action |
|---|---|---|
| Critical | Affects correctness or safety | /fortify or /guard before shipping |
| Important | Affects quality or maintainability | /calibrate in current cycle |
| Nice-to-have | Cosmetic or minor inconsistency | Note for next /refine pass |
Recommended Next Step
After refinement is complete, run /evaluate to verify the polished workflow against realistic scenarios.
NEVER:
- Skip the checklist — go through every item
- Mark items as passing without checking
- Suggest changes that alter behavior (this is polish, not redesign)
- Refine before the workflow is functionally correct (fix first, refine last)
