Tune an existing Codex skill by comparing its intended decision contract with observed decision episodes and outcomes. Use Tune's passive Seq observation and Ledger artifact definitions for `$tune`, intended-vs-observed behavior, missed/false/ceremonial activations, ignored clauses, wrong routes, outcome regressions, repeated workarounds, STE-v1 packets, skill-delta candidates, explicit `$refine` handoff, or commit/push authorization for skill-refinement changes. Stop at audit/proposal unless apply or skill-refinement publication is explicit. Commit/push only with explicit publish intent.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Tune an existing Codex skill by comparing its intended decision contract with observed decision episodes and outcomes. Use Tune's passive Seq observation and Ledger artifact definitions for `$tune`, intended-vs-observed behavior, missed/false/ceremonial activations, ignored clauses, wrong routes, outcome regressions, repeated workarounds, STE-v1 packets, skill-delta candidates, explicit `$refine` handoff, or commit/push authorization for skill-refinement changes. Stop at audit/proposal unless apply or skill-refinement publication is explicit. Commit/push only with explicit publish intent.
Tune
Mission
Improve a skill by finding the smallest evidence-backed change that alters future decisions for the better.
activation evidence asks: was the skill present?
decision evidence asks: what changed because of it?
outcome evidence asks: was that change useful?
Ownership:
$seq reconstructs bounded session evidence under Tune's definition
Ledger validates Tune's authored SKDC/SDR/STE/SDC structures
$tune diagnoses the gap and decides the refinement route
$refine owns in-place skill-package edits after the apply gate passes
The Seq result is evidence, provenance, corpus scope, statistics, and
limitations. It is not an STE packet and grants no authority. Tune classifies
the evidence, compares it with the target contract, authors
skill_tuning_evidence / STE-v1, and validates that packet through:
Free-form evidence rows are candidate mentions, never activation identity.
For historical root scans, bind exclude_session_id to the current
CODEX_THREAD_ID; Seq pushes this exclusion into file preselection so the
audit cannot count its own prompt or tool invocation.
For an executable or tool pattern, invoke the same definition with projection
tools and the exact pattern as needle; treat a tool row as activation only
after Tune verifies the owning command or skill boundary.
The default tools projection emits only tool identity, lifecycle, and
provenance metadata. Use tools-raw only when the user explicitly requests raw
tool payloads and the selected evidence scope is safe to disclose.
Before the first native Ledger command in this workflow, load $ledger and
complete $ledger ensure once.
For watched-session deltas, compare stable source_event_id and line positions
with the prior cursor. If the definition lacks a needed observation, request a
passive observation-definition change or a genuinely domain-independent Seq
operator. Do not request a new skill-specific native command.
Modes
Choose exactly one:
audit-only
proposal-only
apply-with-refine
audit-only: explain what evidence supports and does not support; no edits.
proposal-only: default for "improve," "optimize," or "what should change?"; produce one bounded decision delta, terminal repeat state, or no-action decision; no edits.
apply-with-refine: use only when the user explicitly asks to edit, apply, patch, update, or publish an already-applied skill refinement now. Produce the diagnosis first, then hand a bounded brief to $refine or report the publication-only state. Apply means local file changes; it does not authorize commit or push.
Target skill type
Classify the target before judging it:
decision route selection/rejection/narrowing/blocking/escalation
execution handoff fidelity, surface budget, observed behavior, rework
evidence coverage, precision, provenance, false positives/negatives
orchestration phase correctness, handoff completeness, terminal states, loops
mixed name the relevant dimensions; do not force route-change metrics
Prefer skill_decision_contract / SKDC-v1. If absent, reconstruct only the minimum provisional contract needed for diagnosis and label it contract_authority: inferred. Do not pretend inferred clauses are stable historical identifiers.
Validate an authored contract through Tune's canonical passive definition:
A passing result means only that the contract is structurally valid under the
reported definition digest. Tune retains interpretation and decision authority.
Evidence hierarchy
Use the strongest available evidence and preserve weaker classes separately:
1. SDR-v1 structured decision receipt
2. explicit assistant statement tying skill to a decision
3. explicit skill use plus contract-aligned route/action
4. skill use plus downstream outcome with no route attribution
5. co-occurrence or raw mention
Only levels 1-2 establish a strong skill-caused decision delta. Levels 3-4 support alignment or association, not causal proof. Level 5 is weak evidence.
Ceremonial activation means the skill was loaded or declared but no clause was exercised, no route/scope/proof/lifecycle state changed, and the work is indistinguishable from a no-skill path. Ceremony is not automatically harmful; it becomes a tuning gap when recurrent or costly.
Do not infer alternatives that were never observed. Do not count a later successful session as proof that a skill caused the success.
Before proposing a change, ask whether the observed action plausibly would have happened without the skill, whether the skill changed the route or merely described it, whether compliance improved the outcome, whether missed activation caused failure, and whether a companion skill owns the effect.
For high-impact or ambiguous tuning, use skill_decision_provenance_auditor and/or skill_outcome_skeptic.
Canonical tune packet
Consume or emit skill_tuning_evidence / STE-v1. It must preserve target kind, contract authority, window, denominator, trigger quality, decision influence, clause compliance, outcomes, workarounds, exemplars, recurrent gaps, and limitations.
Skill delta
Produce at most one dominant skill_delta_candidate / SDC-v2 per cycle.
Required fields:
target and type
source packet
gap signature/type
episode and clause refs
evidence class/recurrence/confidence
expected decision delta
smallest change
protected contracts
outcome-observation query
proposed action
publish authorization and commit/push state, when apply-mode is requested
If there is no expected decision delta, do not produce a long redesign.
Validate an authored candidate through Tune's canonical definition:
A pass establishes only structural validity under the reported definition
digest. Tune retains change-selection authority.
Repeat proposal ledger
Track proposal signature, first/last seen, repeat count, evidence delta, state, and next action. If the same proposal appears three times without new decision/outcome evidence, emit one terminal state:
Apply-with-refine may edit files only when all hold:
explicit user request to edit, apply, patch, update, or publish a skill refinement now;
target, evidence source, and intended contract are identified;
protected-skill restrictions are satisfied;
decision/outcome gap is sufficiently evidenced and smallest change is known;
stable clause IDs are preserved unless intentionally replaced;
an outcome-observation query exists when the claimed effect requires later evidence.
Publishing is separate:
commit only after explicit commit, publish, ship, or save-to-git intent exists;
push only after commit succeeds and explicit push or remote-publish intent exists;
otherwise report commit/push as blocked:not-requested.
when publishing was requested but pre-commit or worktree checks fail,
report the specific blocked state instead of collapsing it to blocked:not-requested.
If any required gate fails, stop at audit/proposal or report blocked publication.
Handoffs
$refine handoff: use REFINE-SKILL-v3. The brief must bind source packet, target kind, gap/clause refs, expected delta, optimization boundary, intervention budget, forbidden changes, smallest-change hint, outcome-observation query, and publish authorization when relevant. Do not hand $refine raw transcripts when STE-v1 is available.
Missing observation handoff: identify the physical evidence, the owning passive
definition, the missing generic operator if any, bounds, and acceptance
examples. Never ask Seq to acquire Tune vocabulary or decision authority.
Subagent policy
Default root-only for small, explicit gaps.
Use skill_contract_modeler when the target is decision-oriented and lacks SKDC-v1.
Use skill_decision_provenance_auditor when episodes are numerous or attribution is ambiguous.
Use skill_outcome_skeptic when compliance/outcome correlation could be mistaken for causation.
$refine owns authorized package optimization after $tune produces a bounded packet or brief. Do not delegate this to a system-managed optimizer.
Outcome observation
Rerun the exact seq observe invocation named by the tuning packet when current
evidence can exist. Otherwise retain it as a future observation. A text edit
does not prove that behavior improved.
