octocode-prompt-optimizer

What this skill does

# Prompt Optimizer Skill

<what>
Analyzes and improves instructional prompts, documentation, and agent instructions using prompt engineering best practices while preserving original intent.
</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
- Strengthening agent-operational text without changing business/domain logic
</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 - target line count increase <10%; if >10%, MUST document a one-line justification in VALIDATE

**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:**
- Direct file/system modification that bypasses quality gates
- Any tool usage that executes code or commands unrelated to prompt optimization
- Tools that skip the READ→UNDERSTAND→RATE→FIX→VALIDATE flow

**ALLOWED tools:**
- Read-only file access (to read prompt files)
- Safe file edit/write capability (ONLY after VALIDATE step passes)
- Clarification question capability (for user clarification)
- Text output (all phases)

**Compatibility note (REQUIRED):**
- Map capability names to the active runtime's tool names.
- Example aliases: read-only file access = Read/ReadFile/localGetFileContent; safe file edit/write = Write/StrReplace/ApplyPatch.
- **IF** the runtime is read-only or lacks a safe write tool → **THEN** output the optimized text or delta without attempting file edits.
</tool_control>

<write_policy priority="high">
**Write policy (REQUIRED):**
- **IF** the user asked for review/advice only → **THEN** do not modify files; return the optimized content in chat.
- **IF** the user asked to update a specific file and a safe write tool exists → **THEN** write only after VALIDATE passes.
- **IF** the path is missing, not writable, or unsafe to edit → **THEN** return the optimized content or patch-style delta and state that no file changes were made.
</write_policy>

---

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

### Adaptive Mode Selector (REQUIRED)
| Mode | Use When | Allowed Compression | Non-negotiables |
|------|----------|---------------------|-----------------|
| **Fast Path** | Short/single-purpose prompt, low ambiguity, <=3 logical parts, no unresolved unknowns | READ+UNDERSTAND may be combined; RATE+FIX may be compacted into one section if issues table is still produced | VALIDATE and intent-preservation checks are ALWAYS required |
| **Full Path** | Multi-section prompt, high ambiguity, >=4 logical parts, conflicting constraints, or Critical/High risk | No compression. Execute each gate separately | All gates and templates required |

**Mode selection rules (REQUIRED):**
- **IF** any unknown blocks progress, conflicting instructions exist, or Critical/High issues are likely → **THEN** use Full Path.
- **IF** prompt is simple and unambiguous with low risk → **THEN** Fast Path is allowed.
- **IF** uncertain which mode applies → **THEN** default to Full Path.

### Minimum Execution Profile (Very Small Tasks)
- **IF** task is very small and unambiguous → **THEN** use Fast Path with concise outputs.
- **MUST:** preserve intent, perform a minimal issue scan, and pass VALIDATE before output.
- **MUST:** follow selected output variant format.
- **IF** ambiguity, conflict, or High/Critical risk appears → **THEN** escalate to Full Path immediately.

**Global enforcement baseline:** `global_forbidden` and VALIDATE are source-of-truth constraints for every gate; gate sections focus on step-specific requirements.
</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

### ALLOWED
- Read-only file access only
- Text output to confirm reading

### On Failure
- **IF** file unreadable and inline content exists → **THEN** continue using the provided content
- **IF** file unreadable and no content exists → **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

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