/skill-refine

name: skill-refine
description: "Score and improve an artifact with a frozen rubric, independent models, implemented edits, and bounded rescoring"
disable-model-invocation: true

Rubric-guided refinement

Execute the workflow below when invoked through `/octo:refine` or `/octo:ladder`. This is a host-managed workflow using real provider calls. Never role-play other models or invent their scores. The score validator checks structure and arithmetic; it does not verify the truth of a model's judgments.

Set `OCTO_SKILL_FILE` to the absolute path of this loaded `SKILL.md` supplied by the host. Resolve its installation before reading resources or running commands. This works without a stable plugin link or trusted startup hooks. If the host supplies no skill path, use its explicit plugin root; stop if neither resolves.

OCTO_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${OCTO_ROOT:-}}}"
if [[ -n "${OCTO_SKILL_FILE:-}" ]]; then
  [[ "$OCTO_SKILL_FILE" == /* && -f "$OCTO_SKILL_FILE" ]] || exit 1
  OCTO_ROOT="$(cd "$(dirname "$OCTO_SKILL_FILE")" && pwd -P)"
  while [[ "$OCTO_ROOT" != / && ! -f "$OCTO_ROOT/.claude-plugin/plugin.json" && ! -f "$OCTO_ROOT/.codex-plugin/plugin.json" ]]; do
    OCTO_ROOT="$(dirname "$OCTO_ROOT")"
  done
fi
[[ -n "$OCTO_ROOT" && -f "$OCTO_ROOT/scripts/refinement-judge.sh" && -f "$OCTO_ROOT/scripts/refinement-score.py" && -f "$OCTO_ROOT/scripts/refinement-run.py" && -f "$OCTO_ROOT/skills/skill-refine/SKILL.md" ]] || {
  printf '%s\n' 'Cannot resolve this installed Octopus skill' >&2
  exit 1
}

Keep this absolute root in the workflow context and include its assignment in each new shell invocation. Shell variables may not persist between tool calls. If the judge adapter or score validator is missing at this root, stop and name the missing component rather than running a command with an empty root.

1. Establish scope and budget

Read the supplied artifact and relevant project instructions. Accept text, files, plans, code, images, or other artifacts the host can actually inspect. For binary, visual, or remote artifacts, obtain a faithful readable or rendered snapshot with the appropriate host tools. If you cannot inspect it, stop and name the missing capability. Do not score an unseen attachment or a URL title.

Before any external provider call, including model-assisted research, inspect the candidate, supporting evidence, and accessible project context for credentials and private tokens. Repeat this inspection for new content before dispatch. If secrets are found, stop the run before research or judging and report the affected input or file without quoting its secret values. Do not continue by creating a sanitized copy, changing working directories, or asking a judge to ignore the original. The current adapter restricts writes and tools; it does not enforce isolation from the secret-bearing original or other readable files. Secret-bearing inputs require an execution boundary that prevents those reads, which this adapter does not provide. Host inspection is not an automatic secret scanner or a guarantee of data isolation.

Record the audience, intended outcome, constraints, editable paths, and what must be preserved. A request to improve a plan authorizes editing the plan, not executing the project described by it. A scoring or review-only request produces assessments and proposed revisions without changing the original. Otherwise invocation authorizes scoped improvements to the supplied artifact. Ask only for missing information that prevents a useful, bounded run.

Validate all options before work. Defaults are target 95/100, max five improvement rounds, max 30 elapsed minutes, and max 14 external model calls. `--max-rounds` accepts integers 1 through 10; minutes and calls must be positive integers; target must be finite and between 0 and 100. Preserve explicit budgets. Retries, research, scoring, and model-assisted edits all consume the call budget. Baseline is round zero. Check remaining time and calls before every dispatch, and reserve two scoring calls before starting an improvement. Bound each call by the remaining elapsed budget. Never reset counters on resume or restart a run to evade a limit. Stop after two rounds without verified improvement.

Create a unique run directory in the user's project under `.claude-octopus/refine/<run-id>/`, never in the installed plugin. Check the project's ignore rules before writing sensitive content there. If it is not ignored, use a private directory outside the repository and report its path. Keep the original, best candidate, rubric, model responses, score reports, and an append-only `iterations.jsonl` owned by `scripts/refinement-run.py`. Never append hand-written iteration decisions. Record hashes, actual model IDs and effort, calls, elapsed time, available usage/cost data, changes, and reasons for keeping or rejecting candidates. Unknown monetary cost stays unknown.

Snapshot the exact initial content and existing dirty edits. Work on a candidate copy. Publish only an accepted candidate into the authorized paths after checking that the original has not changed since it was read. Preserve concurrent edits and stop on a conflict. Never use `git reset --hard`, `git clean`, blanket checkout, `git add -A`, or automatic commits to manage these experiments.

Phase loading and fixed judging contract

Use the host's native shell, file inspection, and task tools. On Codex, load `skills/blocks/codex-host-adapter.md` from the resolved plugin root. Do not assume that a host exposes a provider or subagent until its tools confirm availability.

Before each phase, read its entire resource from the resolved installed plugin root, using the exact phase paths listed below. These paths work for both Claude and Codex installations. Stop if a resource is missing. Load only the next phase, and reload its resource after compaction before resuming it:

1. Scope, secret inspection, candidate preservation, and budgets