Optimize Prompt Precision

Iteratively optimize prompt precision through verification loops. Primary goal: ensure prompt cannot be interpreted in ways the author doesn't expect.

Overview

This skill transforms ambiguous prompts into precise ones through:

1. Verification First - prompt-precision-verifier checks for issues before any changes
2. Optimization - Apply targeted fixes based on verifier feedback (infer from context when possible, ask user when not)
3. Re-verification - Verify fixes, iterate if issues remain (max 5 iterations)
4. Output - Atomic replacement only after verification passes

Loop: Read → Verify → (Exit if precise) → Optimize based on feedback → Re-verify → (Iterate if issues) → Output

Key principle: Don't try to optimize in one pass. The verifier drives all changes - if it finds no issues, the prompt is already precise.

Workflow

Phase 0: Create Todo List (TodoWrite immediately)

Create todos tracking workflow phases. List reflects areas of work, not fixed steps.

Starter todos:

- [ ] Input validation
- [ ] Initial verification
- [ ] (Expand: optimization iterations on ISSUES_FOUND)
- [ ] Output optimized prompt

Phase 1: Input Validation

Mark "Input validation" todo in_progress.

Step 1.1: Parse arguments

Extract input from $ARGUMENTS. Determine if file path or inline prompt.

Step 1.2: Handle input type

Step 1.3: Validate content

• If file path: Check file exists using Read tool
• If inline: Write to temp file, note original was inline
• Error if no input provided: "Usage: /optimize-prompt-precision OR /optimize-prompt-precision "

Step 1.4: Store metadata

• source_path: Source file path (or temp path for inline)
• is_inline: Boolean (affects output messaging)
• original_content: Full prompt text
• original_path: /tmp/precision-original-{YYYYMMDDHHMMSS}-{4-lowercase-alphanumeric}.md (copy of original for verifier comparison)
• working_path: /tmp/precision-optimized-{YYYYMMDDHHMMSS}-{4-lowercase-alphanumeric}.md (modified version)

Mark "Input validation" todo completed.

Phase 2: Initial Verification

Mark "Initial verification" todo in_progress.

Step 2.1: Create working copies

Using Write tool:

1. Copy original content to original_path (untouched reference for verifier comparison)
2. Copy original content to working_path (will be modified)

Step 2.2: Run verifier first (single file mode)

Launch prompt-precision-verifier agent via Task tool BEFORE any optimization:

• subagent_type: "prompt-engineering:prompt-precision-verifier"
• prompt: "Verify prompt precision. File: {working_path}. Check for ambiguities, conflicts, undefined terms, underspecified rules, vague thresholds, priority confusion, edge case gaps, and implicit expectations. Report VERIFIED or ISSUES_FOUND with specific details."

Step 2.3: Handle verifier response

• If "VERIFIED": Mark todo completed, proceed directly to Phase 4 (Output) with message: "Prompt is already precise. No changes needed."
• If "ISSUES_FOUND": Mark todo completed, save the issues list, add "Optimization iteration 1" todo and proceed to Phase 3
• If verifier fails or returns unexpected format: Retry once with identical parameters. If retry fails, report error: "Verification failed - cannot proceed without verifier."

Step 2.4: Display verifier findings

If issues found, show user summary and proceed:

Verifier found {count} precision issues. Proceeding with optimization...

Mark "Initial verification" todo completed.

Phase 3: Optimization Loop (Verifier-Driven)

Mark "Optimization iteration 1" todo in_progress.

Key principle: All fixes are driven by verifier feedback. Do NOT analyze the prompt independently - only fix the specific issues the verifier reported.

For each iteration from 1 to 5:

1. Apply fixes from verifier feedback: For each issue in the verifier's report, apply the Suggested Fix or use Resolution Strategy (see below) to address it. Write optimized version to working_path.

   • Only fix issues the verifier identified - do not add your own improvements

2. Re-verify (comparison mode): Launch prompt-precision-verifier agent via Task tool:

   • subagent_type: "prompt-engineering:prompt-precision-verifier"
   • prompt: "Verify optimization. Original: {original_path}. Modified: {working_path}. Check for ambiguities, conflicts, undefined terms, underspecified rules, vague thresholds, priority confusion, edge case gaps, implicit expectations, optimization regressions, and over-optimization. Report VERIFIED or ISSUES_FOUND with specific details."

3. Handle response:

   • If "VERIFIED": mark todo completed, exit loop, proceed to Phase 4
   • If "ISSUES_FOUND" and iteration < 5: mark todo completed, save new issues list, add "Optimization iteration {next}" todo, continue to next iteration
   • If "ISSUES_FOUND" and iteration = 5: mark todo completed with note about unresolved issues, proceed to Phase 4 with warning
   • If verifier fails or returns unexpected format: display error to user, retry once with identical parameters. If retry fails, proceed to Phase 4 with warning: "Verification incomplete - manual review recommended."

Resolution Strategy

For each issue found, follow this decision tree:

Issue detected
    │
    ▼
Can resolution be INFERRED from prompt context?
(purpose, goals, existing patterns, domain conventions)
    │
    ├─ YES → Apply inferred fix directly
    │        Examples:
    │        - "Be concise" in a CLI tool prompt → infer "under 100 words"
    │        - Conflict between "brief" and "thorough" → infer based on prompt's stated purpose
    │        - Undefined "standard format" → infer from examples in prompt or domain norms
    │
    └─ NO → Ask user via AskUserQuestion
             (truly ambiguous, multiple valid interpretations, author intent unclear)

Inference sources (check in order):

1. Prompt purpose/mission - What is this prompt trying to accomplish?
2. Existing patterns - How does the prompt handle similar cases?
3. Domain conventions - What's standard practice in this domain?
4. Sensible defaults - What would a reasonable author likely intend?

When to ask the user:

AskUserQuestion format:

questions: [
  {
    question: "The prompt says '{ambiguous text}'. What did you intend?",
    header: "Clarify: {brief topic}",
    options: [
      { label: "{interpretation A}", description: "{what this means}" },
      { label: "{interpretation B}", description: "{what this means}" },
      { label: "{interpretation C}", description: "{what this means}" }
    ],
    multiSelect: false
  }
]

Batch related questions - If multiple issues need user input, ask up to 4 related questions in one AskUserQuestion call.

After user answers: Apply their clarification to the prompt, then continue optimization loop.

Phase 4: Output

Mark "Output optimized prompt" todo in_progress.

Step 4.1: Apply changes

After optimization complete (verification passed or max iterations reached):

• For file input: mv {working_path} {source_path} (atomic replacement)
• For inline input: Keep at working_path, report location

Step 4.2: Display results

If verification passed:

Optimized: {path}
Iterations: {count}
Status: Precise and unambiguous

Changes applied:
- {summary of fixes}

If verification failed after 5 iterations:

Optimized with warnings: {path}
Iterations: 5
Status: Some issues may remain

Unresolved issues:
- {list from last verification}

Review the changes manually.

Mark "Output optimized prompt" todo completed. Mark all todos complete.

Optimization Techniques

Apply these techniques to fix precision issues:

Key Principles

Edge Cases

Example Usage

# Optimize a prompt file for precision
/optimize-prompt-precision prompts/code-reviewer.md

# Optimize inline prompt for precision
/optimize-prompt-precision You are a helpful assistant. Be concise but thorough. Use good judgment.

# Optimize a skill file for precision
/optimize-prompt-precision claude-plugins/my-plugin/skills/my-skill/SKILL.md

Example Output

Optimized: prompts/code-reviewer.md
Iterations: 2
Status: Precise and unambiguous

Changes applied:
- Defined "significant issues" as errors, security vulnerabilities, or logic bugs (inferred from code review context)
- Resolved conflict between "be thorough" and "keep it brief" by specifying contexts (inferred from prompt purpose)
- Added explicit behavior for empty input case (sensible default)
- Clarified priority when multiple rules apply (asked user - chose "security over style")