octocode-prompt-optimizer

```

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.

---

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

---

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

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 (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

---

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

| 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

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.

---

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 block:

```markdown

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]

```

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]

```

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

---

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

---

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

• Issues Found: [N]
• Fixes Applied: [N]
• Intent Preserved: Yes

| Category | Count | Examples |

|----------|-------|----------|

| Command Strengthening | [N] | [Brief example] |

| Gates Added/Fixed | [N] | [Brief example] |

| Redundancy Removed | [N] | [Brief example] |

[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

---

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.

---

State Summaries (Context Retention)

Use at the start of complex phases to prevent "forgetting":

```markdown

State Summary:

• Goal: [What are we solving?]
• Progress: [What is already done?]
• Next: [Immediate next step]
• Blockers: [Any issues?]

```

REQUIRED: For multi-step fixes, produce a state summary every 3 fixes.

---

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 |

---

| 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.) |

---

| 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 |

---

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 |