dongshuyan/compass-skills / skills/run-history-skill-upgrader
run-history-skill-upgrader
VerifiedUse real run evidence, validation failures, source drift, platform drift, and user feedback to plan and, only after explicit approval, apply structural upgrades to an existing skill. Use when the user asks to improve an existing skill from recent runs, recurring failures, outdated sources, excessive bloat, changed platform behavior, or validated workflow feedback. Do not use to create a brand-new skill or to execute the business workflow itself.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.6 KB |
| agents/openai.yaml | config | 306 B |
| evals/evals.json | config | 5.4 KB |
| references/evidence-and-scope.md | markdown | 2.6 KB |
| references/examples.md | markdown | 2.3 KB |
| references/upgrade-decision-protocol.md | markdown | 2.9 KB |
| references/validation-and-regression.md | markdown | 2.7 KB |
| scripts/test_validate_upgrade_artifacts.py | script | 5.7 KB |
| scripts/validate_upgrade_artifacts.py | script | 13.6 KB |
references/upgrade-decision-protocol.md
View on GitHub# Upgrade Decision Protocol
Read this file while turning evidence into a concrete plan.
## Gate Sequence
Each candidate change should pass these gates in order:
1. `evidence_gate`: is the problem or opportunity grounded in traceable evidence?
2. `generalization_gate`: is the change likely to help future runs, not just one incident?
3. `route_gate`: does the change remove weak subjectivity or move facts to verifiable checks?
4. `net_benefit_gate`: is the gain larger than the cost in length, complexity, or overfitting risk?
5. `validation_gate`: can you show how to prove the change helped or at least did not regress?
## Case Design
Split examples and tests into:
- `incident`: the original failure or confusion;
- `candidate_rule`: the proposed durable behavior;
- `regression_case`: a case that should continue to pass;
- `boundary_case`: a near-negative or over-broad case;
- `holdout_challenge`: a keep-back challenge used only after the change is applied.
Do not use the holdout challenge to invent the rule itself.
## Route Effect Mapping
If the current skill already contains an equivalent rule for a step that failed, check the version used in that run. If the rule was added later, check whether the newer version already addresses the failure. If the rule was present, follow the available evidence:
- Did the entry point match the task, and did the relevant guidance load?
- Did the rule apply under the conditions of that run? Did another instruction conflict with it?
- Was the step carried out? Did the final artifact meet that run's requirements?
Propose the smallest change where the evidence locates the failure, such as repairing a broken reference or checking the final export. If the evidence shows only an incorrect artifact or otherwise leaves the cause unresolved, record the cause as unknown.
Describe the route impact of each planned change with labels such as:
- `delete_weak_route`
- `user_confirmed_route`
- `tool_verified_route`
- `evidence_first_route`
- `merge_duplicate_route`
If you cannot explain who corrects a route when it goes wrong, the route is still weak.
## Upgrade Levels
- `no_change`
- `maintenance_note_only`
- `prune_or_consolidate`
- `local_refactor`
- `cross_reference_refactor`
- `major_refactor`
- `deprecate_or_replace_source`
Prefer the smallest level that solves the real problem.
## Plan Template
For each candidate change, include:
- evidence;
- signal class;
- root cause;
- planned change type;
- affected files or structure owners;
- route effect;
- validation method;
- risks and non-goals.
Also include:
- deletion or merge candidates;
- ideas that were rejected;
- the exact approval needed before application.
## Anti-Overfit Rule
Do not turn these into permanent rules without stronger evidence:
- literal temp paths;
- one-day UI wording;
- account-specific behavior;
- one-time emergency workarounds;
- temporary user preferences not marked as durable.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |