Mission
Improve the measured effectiveness and efficiency of software, agentic systems,
and skill packages. Preserve protected contracts, identify the limiting mechanism,
make an attributable intervention, and verify the result. $tune remains the sole owner
of skill creation, direct editing, and evidence-backed behavioral tuning.
One skill owns diagnosis, selection, and authorized mutation. Keep those phases distinct; do not hand off merely because the target is code rather than a skill.
Select the target before the procedure
| Target | Primary evidence | Required route |
|---|---|---|
| Software: application, library, service, runtime, build, or tool implementation | Representative workload, profile, correctness oracle, resource measurements | performance.md and its software guide |
| Agent system: prompts, tools, retrieval, orchestration, harness, or model configuration | Task evaluations, traces, quality, latency, cost, and failure denominators | performance.md and its agent guide |
| Skill package: creation, specified package change, or behavioral diagnosis | Current package and requested delta; decision episodes when attribution is needed | Skill-package guidance below |
A mixed target loads only the guides implicated by its objective and intervention. For example, an agent latency problem can require software profiling of a tool; a measured skill-overhead problem can require both package authoring and agent measurement. Reuse one objective and evidence set, not parallel dossiers. Do not assume that a prompt edit is the remedy before locating the limiting mechanism.
Software work does not require skill discovery, activation history, a decision
receipt, or agents/openai.yaml. Skill creation and known package edits do not
require unrelated performance benchmarks. Ordinary feature work without a tuning
objective remains outside implicit activation.
Public modes
Choose one intent mode, independently of target and authority:
create -> create a skill when no existing owner covers the intent
edit -> apply a requested concrete change or known defect repair
tune -> diagnose and improve from evidence, including performance optimization
Infer create for an uncovered skill request, edit for a specified change, and
tune for questions about behavior, effectiveness, bottlenecks, or regressions.
An explicit $tune create, $tune edit, or $tune tune overrides mode inference,
not target selection, authority, or validation. create is not a general-purpose
application generator. A specified code optimization in edit mode still follows
the performance route; it cannot bypass baseline or preservation checks.
inspect, apply, target kind, regression, evidence source, publication state,
and terminal result are not modes.
Authority gates
Mutation
inspect forbids changes to the protected target: source/index, repository
history, persistent configuration, canonical evidence, and unrelated files.
Select it for analyze, audit, review, inspect, "what should change?", proposal-only,
or an explicit no-edit request. Read existing evidence and run authorized safe
observations; do not treat an analysis request as implementation authority.
Disposable observation is a separate permission, not a new mode or apply.
When the user or governing workflow authorizes it, a targeted test, scratch
reproduction, or profile may write only established disposable outputs outside
the protected target. Use inspected local commands, isolated synthetic/copy data,
existing tools, and already-authorized resource limits; preserve the source,
canonical custody and unrelated work. A temporary path or test name alone does
not establish safety. Automatic caches, fixtures, logs and cleanup count as writes:
redirect or disable them, or do not execute. Retain only requested output; clean
up only session-owned scratch artifacts when permitted.
Explicit no-file/no-write instructions prohibit even scratch outputs. Do not install tools, create branches, change a benchmarked implementation, write canonical evidence, or invoke unapproved external effects under inspection. Missing disposable-observation authority blocks that observation, not independent read-only analysis. Do not repeatedly seek permission for an already-authorized unchanged safe observation; honor narrower enclosing workflow limits.
apply authorizes changes inside the requested target surface. Select it for
create, edit, fix, update, apply, patch, optimize, or improve when the target and
objective are clear. An explicit prohibition on edits always wins. Diagnose and
freeze the expected delta before tune-mode mutation. A known direct skill edit
does not need a manufactured historical dossier.
Neither authority grants production load, paid evaluations, network access, profiling of unrelated processes, data export, deployment, or relaxed security controls. Use existing permissions and budgets; otherwise report the specific blocked effect while continuing independent authorized work. Redact secrets and private payloads from profiles, traces, fixtures, and published evidence.
Publication
Local mutation does not authorize Git effects.
commit -> explicit commit, save-to-git, publish, ship, or PR intent
push -> explicit remote publication intent after the intended commit succeeds
PR -> explicit PR intent
One attributable experiment need not be one commit. Follow repository integration policy; do not rewrite shared history or discard unrelated work for a benchmark. Report a concrete blocker when requested publication cannot complete.
Skill-package guidance
For a skill-package target, read its SKILL.md, agents/openai.yaml, and existing
decision contract first. Search for an existing owner before creating a package.
Load create.md, edit.md, or tuning.md for the
selected mode. Read authoring.md before selecting or realizing a
package intervention, including proposal-only surgery. It owns progressive
disclosure, cognitive compilation, semantic-weakness selection, package integrity,
and the fresh-eyes pass. A diagnosis ending in no-change need not load authoring.
Load deeper references, scripts, assets, and definitions only when the mode or change depends on them; inspect affected integrations before editing. Root owns every skill-package edit. Retain existing Seq/Ledger ownership and privacy rules; their skill-history adapters are not prerequisites for software benchmarks.
A supported defect in current package text can justify a direct edit. Historical claims about activation, recurrence, influence, or outcomes require behavioral evidence. Preserve the distinctions among activation, decision influence, and outcome causality, and all stable contract IDs. Doctrine vocabulary alone is not a behavioral improvement. Cognitive changes still use the conditional authoring reference; mechanical changes do not acquire a cognitive-compilation ritual.
For a catalog/disclosure, observation-authority, or cross-workflow change, use the relevant cases in workflow-probes.md as package validation, not a startup checklist. An explicitly requested review-economy or review-context evaluation uses review-economy.md within the agent-performance route; it grants no production review credit.
Progressive disclosure: authoring.md. Cognitive compilation: authoring.md. Intervention selection: authoring.md. Decision instrumentation: authoring.md. Package rules: authoring.md. Fresh-eyes pass: authoring.md. Create mode: create.md. Edit mode: edit.md. Skill tune mode: tuning.md.
Common kernel
- Resolve target, objective, mode, authority, and selected guidance.
- Reconstruct only the operative contract: required observations, protected behavior, consequential decisions, authority, stopping conditions, and observable success/failure. For skills, include trigger and non-trigger bounds.
- Acquire the evidence the selected route needs. For performance, establish a representative baseline and identify the limiting mechanism before optimizing.
- Before mutation, freeze in the native workflow, not a new mandatory receipt:
expected delta: from -> to protected behavior and acceptance criterion evidence and its limits selected intervention and why it addresses the mechanism mutation authority - Select one dominant valid intervention per cycle, or no change. For package policy, semantic weakness precedes physical minimality. For performance, compare expected end-to-end benefit, confidence, risk, and cost; do not invent a universal numeric cutoff or choose by diff size alone.
- Apply only when authorized. A coherent intervention can span multiple files. Preserve unrelated behavior, concurrent work, and required evidence.
- Validate the protected contract and the strongest currently observable claim. Code needs a preservation argument and executed evidence; agents need outcome quality as well as resource measurements; packages need integrity and relevant behavioral probes. Tests and checklists are not automatically formal proofs.
- Retain, revise, or discard from evidence. Re-measure and re-profile accepted performance changes because the bottleneck may move. Finish the authorized objective/set; do not stop after the first win or repeat without a discriminator.
- Run a fresh-eyes pass over correctness, routing, authority, and claim strength; use the package-specific pass when editing a skill. Publish only as authorized.
If materially new evidence invalidates the expected delta or selected intervention, return to the contract/evidence step; do not silently broaden scope during editing. For an explicitly requested portfolio pass, select independently per target and finish the authorized set. An available implementation or another skill is not a reason to stop before requested validation and delivery.
Outcome observation and stops
Run a current observation when it can exist within authority. Otherwise retain an exact reproduction/evaluation command or query and identify what remains unproved. Missing tooling permits bounded diagnosis, not fabricated measurements or a claim that an unmeasured patch is faster.
A text edit proves changed text, not activation, reasoning quality, or outcomes. A faster microbenchmark does not establish a faster system. Fewer tokens, model calls, or steps do not establish a better agent. Do not silently trade accuracy, ordering, numerical semantics, reliability, safety, or security for speed. Approximation needs an existing allowance or explicit authorization with bounds.
Stop when the objective is satisfied, no worthwhile supported candidate remains,
the authorized budget is exhausted, or a concrete blocker prevents the next
necessary effect. Distinguish no-change, inconclusive, and blocked; do not
claim global optimality. Rejected experiments do not count as retained gains.
Report
Tuned:
- Target and objective:
- Mode: create | edit | tune
- Mutation: inspect | apply
- Expected delta and protected behavior:
- Evidence and limits:
- Selected intervention:
- Files changed:
- Validation and outcome observation:
- Before/after, variability, and tradeoffs:
- Retained/rejected experiments and stopping reason:
- Publication:
- Remaining uncertainty:
Omit empty or inapplicable fields. Put the useful result last after any execution narration. When changing Tune's scope/routing, use performance-probes.md alongside existing package/cognitive probes; those are change-validation cases, not a startup gate for each optimization.