octocode-prompt-optimizer

name	octocode-prompt-optimizer
description	Use when an agent prompt, tool schema, policy, or handoff needs to get clearer, safer, easier to trigger, cheaper in context, or measurable against real behavior. For SKILL.md folder install/review/structure, use octocode-skills.

Octocode Prompt Optimizer

Optimize instruction behavior, not prose aesthetics.

Flow: READ → UNDERSTAND → RATE → FIX → VALIDATE → OUTPUT.

Lobby rules and gates

• READ: inspect the whole input and its type; UNDERSTAND: map goal, parts, flow, assumptions, and unknowns.
• RATE: record evidenced issues, severity, and baseline; FIX: address Critical/High issues and name deliberate deferrals.
• VALIDATE: prove intent and required behavior remain correct; OUTPUT: provide the requested artifact and truthful delta.
• Use the full path for multi-section, ambiguous, tool-facing, or high-risk work; combine adjacent steps only for short, low-risk text. Never skip VALIDATE.
• Preserve intent, working branches, identifiers, commands, and required metadata; ask before changing them.
• Verify cited commands, flags, paths, tool names, and schemas before rewriting; flag unverified claims.
• Make only critical behavior mandatory; retain preference language for real preferences. Mutate files only with authority.
• Stop when: a material unknown would change intent, scope, or risk (ask one focused question and pause); instruction authority is ambiguous, or resolving a conflict would override user intent; an edit changed intent or working logic (revert it and return to UNDERSTAND); write authority is missing (deliver a patch-style delta instead of a file change); a VALIDATE check fails twice on the same section (report the weakest branch instead of forcing a pass); a reliability gain has no held-out evidence (report it as unmeasured).

Smart routes — load only what the current step needs

• READ and UNDERSTAND: load references/gates.md — read every section and map intent before judging or drafting.
• RATE: load references/rate.md; FIX: load references/fix.md; VALIDATE: load references/validate.md; OUTPUT: load references/output.md — load only the active gate so later-step advice cannot bias the current decision.
• When instructions conflict or a fix needs a compact instruction pattern, load references/patterns.md — apply the higher authority and log the resolution in one line.
• When reducing noise, load references/conciseness-toolkit.md; when fixing priority/hierarchy load references/attention.md; when choosing a technique for an observed failure load references/prompt-techniques.md — match technique to failure mechanism.
• When optimizing tool or MCP contracts, load references/tool-contracts.md; for agent handoffs load references/agent-communication.md; for typed packet boundaries load references/zod-agent-contracts.md — make inputs, outputs, authority, and failure states explicit.
• When context can overflow, load references/context-budget.md; when repeated calls share stable prefixes load references/prompt-caching.md — control relevance, pagination, latency, and cost.
• When reliability must be measured, load references/evaluation-data.md — build realistic held-out scenarios, verifiers, metrics, and a failure ledger.
• When instructions consume retrieved or user-supplied content, load references/untrusted-content.md — preserve the boundary between data and authority.
• When improving this skill, prefer octocode-graph-eval; otherwise load references/improve-loop.md — require measurable acceptance instead of intuition.

Related routes

• Use octocode-skills for skill-folder architecture/review; octocode-research to verify cited contracts; octocode-graph-eval for held-out behavior.
• Use octocode-subagent for delegation topology.

Done gate

• This skill ships no scripts: every gate above is model-driven, so never report a check you did not actually perform.
• Done requires VALIDATE passed, the OUTPUT variant matching the request, and the reported before/after score, changed files, and deferrals all matching reality.