---
name: octocode-prompt-optimizer
description: Activate when user provides a prompt, SKILL.md, or agent instruction and requests optimization. Transforms weak instructions into reliable, enforceable agent protocols.
---

# Prompt Optimizer Skill

<what>
Analyzes and improves prompts, documentation, and agent instructions using prompt engineering best practices.
</what>

<when_to_use>
- Creating or improving prompts
- Agents skip steps or ignore instructions
- Instructions lack enforcement
- Output format is inconsistent
- Reviewing any instruction document or prompt
</when_to_use>

<global_forbidden priority="maximum">
**CRITICAL - FORBIDDEN at ALL times:**
1. Changing good parts that already work
2. Changing the existing logic/intent of prompts
3. Making changes before understanding the prompt
4. Leaving weak words in critical sections
5. Outputting without validation
6. Over-strengthening soft guidance
7. Skipping gates or checkboxes
8. Bloating prompts - fixes MUST NOT increase line count >10% unless adding required gates

**Triple Lock:**
- **STATE:** You MUST preserve working logic AND follow all gates in order
- **FORBID:** FORBIDDEN: Altering intent without user approval
- **FORBID:** FORBIDDEN: Skipping steps or gates
- **REQUIRE:** REQUIRED: Validate all changes before output AND complete all checkboxes

**Violation invalidates optimization. Start over if violated.**
</global_forbidden>

<tool_control priority="high">
**FORBIDDEN tools during optimization:**
- Shell commands that modify files directly
- Any tool that executes code
- Tools that skip the READ→UNDERSTAND→RATE→FIX→VALIDATE flow

**ALLOWED tools:**
- Read (to read prompt files)
- StrReplace/Write (ONLY after VALIDATE step passes)
- AskQuestion (for clarification)
- Text output (all phases)
</tool_control>

---

## Execution Flow

<execution_flow>
```
READ → UNDERSTAND → RATE → FIX → VALIDATE → OUTPUT
  ↓         ↓          ↓       ↓         ↓          ↓
 GATE      GATE       GATE    GATE      GATE       GATE
```

| Step | Action | Gate Requirement | FORBIDDEN Until Gate Passes |
|------|--------|------------------|----------------------------|
| 1 | **READ** the prompt completely | All checkboxes checked | Analysis, changes |
| 2 | **UNDERSTAND** what the prompt does | Understanding output produced | Rating, fixes |
| 3 | **RATE** each part for issues | Issues table produced | Fixing issues |
| 4 | **FIX** issues by severity | All Critical/High fixed | Validation |
| 5 | **VALIDATE** against checklist | All REQUIRED checks pass | Output |
| 6 | **OUTPUT** optimized document | Format followed exactly | N/A |

**CRITICAL:** You MUST complete each gate before proceeding. DO NOT skip steps.
</execution_flow>

---

## Step 1: READ

<read_gate>
**STOP. DO NOT proceed to analysis.**

### Pre-Conditions
- [ ] User provided prompt/file to optimize
- [ ] Path is valid and readable

### Actions (REQUIRED)
1. MUST read the input file completely
2. MUST note the document type and purpose
3. MUST count approximate line count

### Gate Check
**Verify before proceeding:**
- [ ] File read completely (no skipped sections)
- [ ] Document type identified
- [ ] Line count noted

### FORBIDDEN
- Making ANY changes before reading
- Skipping sections
- Proceeding without completing all checkboxes

### ALLOWED
- Read tool only
- Text output to confirm reading

### On Failure
- **IF** file unreadable → **THEN** ask user for correct path
- **IF** file empty → **THEN** ask user to provide content
</read_gate>

---

## Step 2: UNDERSTAND

<understand_gate>
**STOP. DO NOT proceed to rating. Understand what this prompt does first.**

### Pre-Conditions
- [ ] Step 1 (READ) completed
- [ ] File content in context

### Actions (REQUIRED)
1. MUST identify the **goal** - what is this prompt supposed to achieve?
2. MUST identify **logical parts** - break down into sections/phases/steps
3. MUST identify **flow** - how do the parts connect?
4. MUST document understanding in output format below

### Output Format (REQUIRED)
```markdown
## Understanding

**Goal:** [What the prompt achieves]

**Logical Parts:**
1. [Part name] - [purpose]
2. [Part name] - [purpose]
...

**Flow:** [How parts connect]
```

### Assumptions & Unknowns (REQUIRED if prompt is underspecified)
```markdown
## Assumptions & Unknowns

**Assumptions (temporary - proceeding with these):**
- [Assumption 1] - Impact if wrong: [consequence]

**Unknowns (MUST ask before proceeding):**
- [Unknown 1] - Why critical: [reason]

**Clarification needed:** Yes/No
```
**IF** Unknowns exist → **THEN** STOP and ask user before proceeding to RATE.

### Gate Check
**Verify before proceeding:**
- [ ] Goal clearly stated
- [ ] All logical parts identified
- [ ] Flow documented
- [ ] Understanding output produced

### Reflection
- Did I understand the intent correctly?
- Did I identify all logical parts?
**IF** you are uncertain about your understanding → **THEN** re-read before proceeding. DO NOT guess.

### FORBIDDEN
- Proceeding without understanding the goal
- Making changes based on assumptions
- Skipping output format

### ALLOWED
- Text output (understanding summary)
- Re-reading file if needed

### On Failure
- **IF** intent unclear → **THEN** ask user for clarification
- **IF** multiple interpretations → **THEN** present options and WAIT for user choice
</understand_gate>

---

## Step 3: RATE

<rate_gate>
**STOP. DO NOT fix anything yet. Rate each logical part for issues first.**

### Pre-Conditions
- [ ] Step 2 (UNDERSTAND) completed
- [ ] Understanding output produced

### Issue Categories (MUST check all)

| Category | What to Look For | Severity |
|----------|------------------|----------|
| **Weak Words** | "consider", "might", "could", "may", "should" in critical sections | Critical |
| **Missing Enforcement** | Rules without FORBIDDEN/ALLOWED | High |
| **Ambiguous Instructions** | "do some", "handle", "process" without specifics | High |
| **Referential Ambiguity** | "it", "this", "that", "above", "below" without clear antecedent | High |
| **Missing Output Format** | Expected outputs without templates | Medium |
| **Missing Gates** | Phase transitions without checkpoints | Medium |
| **Duplication** | Same logic/rule repeated in multiple places (not just examples) | Medium |
| **Verbose/Bloat** | Sections >20 lines that could be tables; prose without constraints | Medium |
| **Emoji as Instructions** | Emojis used as commands instead of strong words | Medium |
| **Redundancy** | Same example repeated, unnecessary variations | Low |
| **Low Density** | Explanations that don't constrain behavior | Low |

### Rating Output (REQUIRED)
```markdown
## Issues Found

| Part | Issue | Severity | Fix Needed |
|------|-------|----------|------------|
| [Part name] | [Description] | Critical/High/Medium/Low | [What to do] |
```

### Gate Check
**Verify before proceeding:**
- [ ] All logical parts rated
- [ ] Weak word scan completed
- [ ] Issues table produced
- [ ] Severity assigned to each issue

### FORBIDDEN
- Fixing issues before completing rating
- Ignoring critical issues
- Skipping weak word scan
- Proceeding without issues table

### ALLOWED
- Text output (issues table)
- Re-reading parts for rating

### On Failure
- **IF** no issues found → **THEN** MUST double-check with weak word scan
- **IF** scan still clean → **THEN** document "No issues found" and proceed
</rate_gate>

### Weak Word Reference

| Weak Word | Context | Replacement |
|-----------|---------|-------------|
| consider, might, could, may | Critical section | **MUST**, **REQUIRED** |
| consider, might, could, may | Optional guidance | Remove or keep with "optionally" |
| should, prefer | Critical section | **MUST** |
| should, prefer | Soft guidance | Keep as-is |
| do some, handle, process | Any | Specify exact action: "Run X", "Call Y" |
| as needed, if necessary | Any | **IF** [condition] → **THEN** [action] |
| feel free to, you can | Required action | Remove entirely, use **MUST** |
| feel free to, you can | Optional action | "Optionally, you may..." |

**CRITICAL:** Weak words in FORBIDDEN/MUST/NEVER sections MUST be replaced.

---

## Step 4: FIX

<fix_gate>
**STOP. Fix issues in priority order: Critical → High → Medium → Low.**

### Pre-Conditions
- [ ] Step 3 (RATE) completed
- [ ] Issues table produced

### Fix Priority (MUST follow order)
1. **Critical first** - Weak words in MUST/FORBIDDEN contexts
2. **High next** - Missing enforcement, ambiguous instructions
3. **Medium** - Missing output formats, missing gates
4. **Low last** - Redundancy, density (only if value added)

### Command Strength Hierarchy

| Strength | Keywords | Use For |
|----------|----------|---------|
| Absolute | NEVER, ALWAYS, MUST, FORBIDDEN, CRITICAL | Non-negotiable rules |
| Stop | STOP, HALT, DO NOT proceed, WAIT | Gates/checkpoints |
| Required | REQUIRED, MANDATORY | Essential steps |
| Soft | should, prefer | Optional guidance only |

### Triple Lock Pattern (REQUIRED for Critical Rules)
```
1. STATE: "You MUST X"
2. FORBID: "FORBIDDEN: Not doing X"
3. REQUIRE: "REQUIRED: Verify X complete"
```

### Reasoning Block (REQUIRED Before Changes)
**REQUIRED:** Before making changes, produce a `<reasoning>` block:
```markdown
<reasoning>
1. **Current state:** [What exists now]
2. **Goal:** [What we are trying to achieve]
3. **Approach:** [Why this specific change]
4. **Risk:** [What could go wrong]
</reasoning>
```

### Gate Template (When Adding Gates)
```markdown
<[name]_gate>
**STOP. DO NOT proceed. [What to verify]**

### Pre-Conditions
- [ ] [Previous step completed]

### Actions (REQUIRED)
1. [Action]

### Gate Check
**Verify before proceeding:**
- [ ] [Condition]

### FORBIDDEN
- [What not to do]

### ALLOWED
- [What is permitted]

### On Failure
- **IF** [condition] → **THEN** [recovery]
</[name]_gate>
```

### Gate Check
**Verify before proceeding:**
- [ ] All Critical issues fixed
- [ ] All High issues fixed
- [ ] Medium/Low addressed or documented as skipped
- [ ] Reasoning block produced before changes

### FORBIDDEN
- Over-strengthening soft guidance (keep "should" for optional items)
- Changing logic that already works
- Adding unnecessary complexity
- Skipping Critical/High issues
- Bloating: fixes that increase line count >10% without adding required gates

### ALLOWED
- Text output (draft fixes)
- Iterating on fixes

### On Failure
- **IF** over-strengthening detected → **THEN** revert and re-assess using RATE step criteria
- **IF** unsure if logic changed → **THEN** compare before/after intent
</fix_gate>

---

## Step 5: VALIDATE

<validate_gate>
**STOP. DO NOT output yet. Validate all fixes against checklist.**

### Pre-Conditions
- [ ] Step 4 (FIX) completed
- [ ] All Critical/High issues addressed

### Validation Checklist (MUST complete all)

**REQUIRED checks:**
- [ ] No weak words in critical sections
- [ ] Critical rules use MUST/NEVER/FORBIDDEN
- [ ] No conversational filler
- [ ] No conflicting instructions
- [ ] Logical flow preserved
- [ ] Original intent preserved
- [ ] Triple Lock applied to critical rules
- [ ] Line count increase <10% (unless adding required gates)

**Additional checks (if applicable):**
- [ ] Gates have Pre-Conditions, Gate Check, FORBIDDEN, ALLOWED, On Failure
- [ ] Outputs have format specifications
- [ ] IF/THEN rules for decision points

**Referential Clarity (MUST check):**
- [ ] No ambiguous pronouns or positional references without explicit antecedent
- [ ] All entities have stable names (same term throughout)
- [ ] Steps/outputs referenced by name, not position
- [ ] All cross-references are unambiguous
- [ ] No implicit "the" references without clear antecedent
- [ ] XML tags for attention-critical sections

### Reflection (REQUIRED)
MUST answer these questions:
1. Would I trust this prompt to execute reliably?
2. What's the weakest remaining section?
3. Did I change any original intent? (MUST be NO)

**IF** weakness identified → **THEN** fix or document as limitation
**IF** intent changed → **THEN** STOP and revert. Return to UNDERSTAND step.

### Definition of Done (DoD) - Fast Final Gate
**ALL must be true before OUTPUT:**
- [ ] Single execution path (no ambiguous branches)
- [ ] All inputs/outputs explicitly defined
- [ ] All decision points use IF/THEN
- [ ] No orphan references (every "it/this" resolved)

### Gate Check
**Verify before proceeding:**
- [ ] All REQUIRED checks pass
- [ ] Reflection questions answered
- [ ] No intent changes

### FORBIDDEN
- Outputting without completing validation
- Skipping checklist items
- Proceeding with failed checks

### ALLOWED
- Text output (validation results)
- Returning to FIX step

### On Failure
- **IF** validation fails → **THEN** return to FIX step
- **IF** intent changed → **THEN** return to UNDERSTAND step
</validate_gate>

---

## Step 6: OUTPUT

<output_gate>
**STOP. Verify VALIDATE step passed before outputting.**

### Pre-Conditions
- [ ] Step 5 (VALIDATE) completed
- [ ] All REQUIRED checks passed
- [ ] No intent changes confirmed

### Output Format (REQUIRED - DO NOT deviate)

```markdown
# Optimization Complete

## Summary
- **Issues Found:** [N]
- **Fixes Applied:** [N]
- **Intent Preserved:** Yes

## Changes Made
| Category | Count | Examples |
|----------|-------|----------|
| Command Strengthening | [N] | [Brief example] |
| Gates Added/Fixed | [N] | [Brief example] |
| Redundancy Removed | [N] | [Brief example] |

## Optimized Document
[Full optimized content]
```

### FORBIDDEN
- Deviating from output format
- Outputting without validation pass
- Omitting the optimized document

### ALLOWED
- StrReplace/Write to save optimized content
- Text output (summary + document)

### On Failure
- **IF** format deviates → **THEN** regenerate output
- **IF** user requests changes → **THEN** return to FIX step
</output_gate>

---


## Reference: Instruction Precedence

<precedence_table>
**When rules conflict, follow this precedence (highest wins):**

| Priority | Category | Examples | Notes |
|----------|----------|----------|-------|
| 1 (highest) | Safety/Tool Restrictions | FORBIDDEN tools, NEVER actions | Always wins |
| 2 | User explicit request | "I want X", "Do Y" | Overrides defaults |
| 3 | FORBIDDEN/MUST rules | "FORBIDDEN: changing logic" | Overrides preferences |
| 4 | Skill defaults | Default behaviors, templates | Baseline |
| 5 (lowest) | Soft guidance | "prefer", "consider" | Yields to all above |

**Resolution rule:** When two rules conflict, the higher priority wins. Document the conflict and resolution.
</precedence_table>

---

## Reference: Context Patterns

<reasoning_patterns>
### State Summaries (Context Retention)
Use at the start of complex phases to prevent "forgetting":
```markdown
<phase_start>
**State Summary:**
- **Goal:** [What are we solving?]
- **Progress:** [What is already done?]
- **Next:** [Immediate next step]
- **Blockers:** [Any issues?]
</phase_start>
```

**REQUIRED:** For multi-step fixes, produce a state summary every 3 fixes.
</reasoning_patterns>

---
## Reference: High-Value vs Low-Value Content

<content_guide>
### REMOVE (Low Value)
| Pattern | Action |
|---------|--------|
| Explanatory prose without actionable constraints | DELETE |
| Numeric scoring systems | Replace with pass/fail |
| Repeated examples | Keep 1-2 best |
| Long prose paragraphs | Convert to tables |
| Hedging language | Replace with MUST or DELETE |
| Emoji as instructions | Replace with strong command words (unless prompt output requires emoji) |

### KEEP (High Value)
| Pattern | Example |
|---------|---------|
| Tables with actions | `| Pattern | Action |` |
| Imperative verbs | STOP, EXECUTE, VERIFY |
| FORBIDDEN/ALLOWED lists | Clear capability control |
| IF/THEN conditionals | `**IF** X → **THEN** Y` |
| Gate checkpoints | STOP before transitions |
</content_guide>

---

## Quick Reference

| Goal | Pattern |
|------|---------|
| Force a stop | `**STOP. DO NOT proceed.**` |
| Require action | `**REQUIRED:** You MUST [action]` |
| Ban action | `**FORBIDDEN:** [action] until [condition]` |
| Force format | `**OUTPUT FORMAT (REQUIRED):** [template]` |
| Create checkpoint | `### Gate Check` with `- [ ]` items |
| Handle errors | `**IF** [error] → **THEN** [recovery]` |
| Critical rule | Triple Lock: STATE + FORBID + REQUIRE |
| Replace emoji | Emoji → strong command word (MUST, FORBIDDEN, etc.) |

---

## Common Mistakes

<common_mistakes>
| Mistake | Why It Fails | Fix |
|---------|--------------|-----|
| Skipping UNDERSTAND step | Fixes wrong things, breaks working logic | ALWAYS produce Understanding output first |
| Fixing before RATE complete | Misses issues, inconsistent severity handling | Complete issues table before ANY fix |
| Over-strengthening soft guidance | "prefer" → "MUST" breaks optional flexibility | Keep "should/prefer" for truly optional items |
| Using "it/this/that" | Agent loses context, applies fix to wrong element | Name every entity explicitly |
| Outputting without VALIDATE | Weak words remain, conflicts undetected | MUST complete all checklist items |
| Changing working logic | User trusted original behavior | FORBIDDEN: If the logic works, don't touch it |
| Bloating the prompt | Verbose fixes overwhelm context, reduce density | MUST keep fixes concise; <10% line increase |
</common_mistakes>

---

## Before/After Example

<before_after_example>
### Before (Weak)
```
Consider checking the file before making changes.
You should validate the output.
Handle any errors that occur.
If needed, retry the operation.
```

### After (Strong)
```
**REQUIRED:** You MUST read the file completely before making ANY changes.
**FORBIDDEN:** Outputting without validation.

### On Error
- **IF** file unreadable → **THEN** ask user for correct path
- **IF** validation fails → **THEN** return to FIX step

### Retry Logic
- **IF** operation fails AND retry_count < 3 → **THEN** retry with exponential backoff
- **IF** retry_count >= 3 → **THEN** STOP and report failure to user
```

### Changes Applied
| Original | Issue | Fixed |
|----------|-------|-------|
| "Consider checking" | Weak word in critical action | "REQUIRED: You MUST" |
| "should validate" | Weak enforcement | "FORBIDDEN: without validation" |
| "Handle any errors" | Ambiguous instruction | Explicit IF/THEN for each error |
| "If needed, retry" | Vague condition | Specific retry count + backoff |
</before_after_example>