PDCA: tune-skill

Assignment contract

Methodology: PDCA (pdca)

Task: Improve one existing agent skill against a concrete observed behavior complaint by making the smallest evidence-backed change inside that skill package, while routing methodology, original task-contract, multi-skill, and self-tuning problems to their owning workflow instead of patching them.

Audience: Agents maintaining skills in this repository and humans reviewing proposed skill changes.

Context: Authority: Resolve and obey repository instructions, then locate the maintained source copy. Installed and runtime copies are evidence only and remain read-only during this skill; global copies are always read-only. Any later installation or synchronization is a separate human-owned task outside tune-skill. Preserve unrelated working-tree changes. Never commit, push, install, or modify global copies.

PDCA operating frame:

Plan: Read the target SKILL.md end to end, its behavior-relevant linked resources, the failed output or conversation, and any available source/runtime difference. Lock one complaint contract containing the behavior class, evidence, expected behavior, and preservation boundary. Obtain facts from artifacts rather than the user. If a material product or scope decision remains ambiguous, run a bounded Interview of at most three questions: ask one question at a time, state the artifact facts that leave the decision open, include the recommended answer, and make no change until shared understanding is explicit. An Interview turn also uses the four-line output: Result: blocked; Change names the unresolved decision and confirms no edit; Evidence gives the relevant artifact facts plus the recommendation; Next contains exactly one question for the human. If a controlling ambiguity remains after three questions, stay blocked and name it; do not guess or continue interviewing. Before classification, return blocked when available evidence cannot determine which class owns the complaint; missing direct-edit approval does not prevent classification but always prevents Do. Otherwise use the first matching class in this precedence: (1) self-tuning always returns to methodology-selector and methodology-skill-creator from a separate design/creation session that is not recursively running the current tune-skill; (2) external-cause when tools, permissions, or stale runtime copies fully explain the reported behavior; (3) return-to-methodology when a methodology-generated skill selected the wrong method; (4) return-to-contract when its selected method is valid but its original eight fields are wrong; (5) return-to-loop for multi-skill, shared-contract, architectural, outside-package, broad redesign, or any correction whose responsibility is not one direct tune; (6) direct-tune only when the remaining cause and complete correction stay inside one target package; otherwise blocked. A specific earlier class is not reclassified merely because its resolution occurs outside the target package. Use exact owners: return-to-methodology goes to methodology-selector and then methodology-skill-creator; return-to-contract rebuilds the eight-field methodology-selector contract and then returns to methodology-skill-creator; return-to-loop goes to loop-orchestrator with a new loop-goal intent; external-cause goes to the human or tool/runtime owner named by the evidence; blocked goes to the human who owns the missing evidence or authority. For direct-tune, trace the failed output back to the instruction, omission, conflict, or workflow order that allowed it. Plan the smallest behavioral change that fixes the complaint and one adjacent case without disturbing preserved behavior. Present the complaint, evidence-backed diagnosis, exact target-package files, proposed behavioral change, preserved behavior, and validation plan. The approval proposal itself must use the four-line output: Result: blocked; Change names the exact files, proposed behavior, and preserved behavior; Evidence compresses the complaint, diagnosis, and validation plan; Next asks the human to approve or correct that exact scope. Wait for human approval unless that same proposal was already approved after being shown.

Do: After approval, edit only the causally required files inside the one target skill package, including its SKILL.md, references, evals, or scripts when necessary for one coherent correction. If new evidence makes another package, shared contract, methodology, or original contract relevant, stop before widening the edit, return to Plan, and reclassify under the same precedence using the current evidence. Do not automatically revert, reset, or discard changes already made. When reclassification occurs after an edit, return Result: blocked; list the exact partial files and state in Change, give the reclassification evidence in Evidence, and name the human plus owning workflow that must decide whether to preserve or revert them in Next. Do not mix unrelated cleanup into the change.

Check: Inspect the complete target-package diff and run available structural validators. All behavioral validation is non-mutating by default: use read-only artifacts or an isolated harness, and do not let a tester edit the shared repository or runtime, synchronize installed/global copies, contact external systems, or perform another consequential action. If valid proof requires mutation, stop for separate authority; inability to obtain safe proof prevents completion. Reproduce the original failure or the smallest evidence-equivalent case, run one adjacent case that would expose example-specific overfitting, and obtain a non-mutating independent cold-read against the complaint and prior version or diff. A Markdown check is not behavioral evidence. If a check cannot run or fails, do not claim completion; return to Plan with a new proposal, route, or block.