Skip to content

dongshuyan/compass-skills / skills/run-history-skill-upgrader

run-history-skill-upgrader

Verified

Use 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.

references/evidence-and-scope.md

View on GitHub
# Evidence And Scope

Read this file before drafting the upgrade plan.

## Target Lock

Always lock:

- target skill name;
- absolute or repository-relative path;
- requested scope;
- whether the user asked for plan-only or has already approved a specific plan.

## Evidence Priority

1. Current target-skill files.
2. User feedback and corrections.
3. Real run outputs: logs, tests, screenshots, artifacts, diffs.
4. Official docs or first-party repos that explain source or platform drift.
5. Public references used for pattern comparison only.

## Allowed By Default After Scope Lock

- current visible conversation;
- target skill files inside the agreed repository;
- user-provided artifacts, logs, screenshots, and transcripts;
- repository diffs and test output tied to the current run.

## Explicit Approval Required

- unrelated local session archives;
- browser cookies, local storage, saved sessions, or account caches;
- passwords, tokens, API keys, MFA material, or other credentials;
- unrelated private folders outside the agreed project scope.

## Signal Classes

Use one or more of these labels:

- `process_gap`
- `validation_gap`
- `source_drift`
- `platform_drift`
- `user_preference`
- `candidate_idea`
- `incident`
- `routing_gap`
- `content_bloat`

The label shapes the upgrade plan. An `incident` alone does not justify a durable rule. A repeated `validation_gap` often does.

## Snapshot Discipline

Before file edits, keep at least one of:

- a diff reference;
- a snapshot path;
- an unmodified branch state that can be compared later.

If that is not practical, say so in the plan and treat it as extra risk.

## Strong And Weak Evidence

Strong:

- reproducible failure;
- the same user correction across independent tasks;
- validator or test output;
- official source or platform change.

If you cite recurrence to justify a lasting rule, state how many independent tasks showed the issue, or say that their independence is unknown. Count continuations, forks, retries, and duplicate exports of the same task once. Retries that reproduce the failure support its reproducibility within that task. A single verified defect can justify a targeted fix.

Weak unless corroborated:

- one timeout;
- one vague complaint;
- one private temp path;
- one speculative idea;
- one search result snippet not opened and checked.

## When To Choose No Change

Prefer `no_change` or `maintenance_note_only` when:

- the evidence is weak or one-off;
- the proposed rule would hardcode a path, date, account, or temporary workaround;
- the change increases complexity without adding validation or clarity;
- the user preference was clearly task-local rather than durable.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall