Upgrade

If these files don't exist, use universal defaults.

EXECUTE NOW

Target: $ARGUMENTS

Parse immediately:

• If target contains a specific skill name (e.g., "upgrade reduce"): check only that skill
• If target contains "--all": check all generated skills
• If target is empty: check all generated skills (same as --all)

START NOW. Reference below defines the upgrade process.

Why Consultation, Not Hashing

Skills do not upgrade through hash comparison against a generation manifest. Hash comparison answers a narrow question: "Has this file changed?" Meta-skill consultation answers the right question: "Is this skill's approach still the best approach given what we know?"

A skill could be unchanged but outdated because the knowledge base has grown. Or a skill could be heavily edited by the user but already incorporate the latest thinking through a different path. Reasoning about methodology is more valuable than diffing bytes.

Two Upgrade Paths

Generated skills and meta-skills follow fundamentally different upgrade mechanisms:

/upgrade evaluates generated skills. It cannot evaluate itself or other meta-skills — that is the plugin maintainers' responsibility.

Step 1: Inventory Current System

Gather the vault's current state:

1. Read ops/derivation.md for:

   • Original derivation state
   • Engine version that generated the system
   • Domain description and dimensional positions

2. Read ops/generation-manifest.yaml (if exists) for:

   • Skill versions and generation timestamps
   • Which plugin version generated each skill

3. List all installed skills:

   # Find all skill directories with SKILL.md
   for dir in .claude/skills/*/; do
     skill=$(basename "$dir")
     version=$(grep '^version:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
     gen_from=$(grep '^generated_from:' "$dir/SKILL.md" 2>/dev/null | head -1 | awk -F'"' '{print $2}')
     echo "$skill  v$version  (from $gen_from)"
   done
   

4. Read ops/config.yaml for current dimensional positions

5. Check for user modifications:

   # Detect skills modified after generation
   for dir in .claude/skills/*/; do
     skill=$(basename "$dir")
     file="$dir/SKILL.md"
     [[ ! -f "$file" ]] && continue
     # Check git status — modified files indicate user customization
     git_status=$(git status --porcelain "$file" 2>/dev/null)
     if [[ -n "$git_status" ]]; then
       echo "MODIFIED: $skill"
     fi
   done
   

Present inventory:

--=={ upgrade : inventory }==--

System: {domain description}
Engine: arscontexta-{version}
Skills: {count} installed ({modified_count} user-modified)

  Skill               Version  Generated From    Modified
  /{vocabulary.reduce}    1.0  arscontexta-v1.6  no
  /{vocabulary.reflect}   1.0  arscontexta-v1.6  yes
  ...

Step 2: Consult Knowledge Base

For each generated skill (or the specific skill if targeted), consult the plugin's bundled knowledge base to evaluate whether the skill's current approach reflects current best practices.

Knowledge Base Tiers

Read from the plugin's four content tiers:

Notes in methodology/ are differentiated by their kind: frontmatter field:

• kind: research — WHY: principles and cognitive science grounding (213 claims)
• kind: guidance — HOW: operational procedures and best practices (9 docs)
• kind: example — WHAT IT LOOKS LIKE: domain compositions (12 examples)
• type: moc — Navigation: topic maps linking related notes (15 maps)

Consultation Process Per Skill

For each skill being evaluated:

1. Read the current vault skill — understand its complete approach, quality gates, edge case handling

2. Read relevant knowledge base documents:

   • Research claims about this skill's domain (e.g., for /{vocabulary.reduce}: claims about extraction methodology)
   • Guidance docs about processing pipeline best practices
   • Reference docs about the skill's operational patterns

3. Compare methodology, not text:

   • Does the skill implement the quality gates the knowledge base recommends?
   • Does it handle edge cases the knowledge base identifies?
   • Does it use the discovery/search patterns the knowledge base recommends?
   • Has the knowledge base added new techniques since this skill was generated?

4. Classify each finding:

   Classification	Meaning	Example
   Current	Skill reflects knowledge base best practices	No action needed
   Enhancement	Knowledge base adds technique the skill lacks	New quality gate, better search pattern
   Correction	Knowledge base contradicts skill's approach	Outdated methodology, known anti-pattern
   Extension	Knowledge base covers scenario skill ignores	New edge case, new domain pattern

5. Check user modifications: If the skill has been modified by the user, read both the current (user-modified) version and evaluate whether:

   • The user's changes already incorporate the improvement (skip it)
   • The user's changes are orthogonal to the improvement (can coexist)
   • The user's changes conflict with the improvement (flag for side-by-side review)

Step 3: Generate Upgrade Plan

For each skill with available improvements, create a structured proposal:

Skill: /{domain:skill-name}
Status: {current | enhancement | correction | extension}
User-modified: {yes | no}

Current approach:
  {2-3 sentences describing what the skill currently does}

Proposed improvement:
  {2-3 sentences describing what would change}

Research backing:
  {Specific claims from the knowledge base that support this change}
  - "{claim title}" — {how it applies}
  - "{claim title}" — {how it applies}

Impact: {what changes for the user's workflow}
Risk: low | medium | high
Reversible: yes (previous version archived to ops/skills-archive/)

Risk Assessment

Side-by-Side for User-Modified Skills

When a skill has been modified by the user AND an upgrade is available, show a side-by-side comparison:

Skill: /{domain:skill-name} (USER-MODIFIED)

Your version:                     Recommended:
  [relevant section excerpt]        [what knowledge base suggests]

Your customization:
  {description of what the user changed and why it appears intentional}

Options:
  (a) Keep your version unchanged
  (b) Apply upgrade, preserving your customizations
  (c) Apply upgrade, replacing your version (archived to ops/skills-archive/)

Option (b) requires the upgrade to be compatible with the user's changes. If they conflict, explain why and recommend (a) or (c).

Step 4: Present Plan

--=={ upgrade }==--

Plugin: arscontexta-{current_version}
Knowledge base: {count} research claims, {count} guidance docs
Skills checked: {count}

Upgrades available: {count}
  Enhancements: {n}  |  Corrections: {n}  |  Extensions: {n}

  1. /{domain:skill-name}
     Type: Enhancement
     Change: {one-line summary}
     Research: "{claim title}"
     Risk: low

  2. /{domain:skill-name} (USER-MODIFIED)
     Type: Correction
     Change: {one-line summary}
     Research: "{claim title}", "{claim title}"
     Risk: medium
     Note: Side-by-side comparison available

  ...

{If no upgrades:}
  All {count} skills reflect current best practices.
  No upgrades needed.

Apply all? Select specific upgrades (e.g., "1, 3")?
Or "show 2" for side-by-side detail on a specific skill.

Wait for user response. Do NOT proceed without explicit approval.

Step 5: Apply Approved Upgrades

For each approved upgrade:

5a. Archive Current Version

mkdir -p ops/skills-archive
SKILL_NAME="{skill-name}"
DATE=$(date +%Y-%m-%d)
cp ".claude/skills/${SKILL_NAME}/SKILL.md" \
   "ops/skills-archive/${SKILL_NAME}-${DATE}.md"

5b. Generate Updated Skill

1. Read the skill's generation block from the plugin (if available)
2. Apply the specific improvements identified in Step 2
3. Preserve the user's vocabulary transformation from ops/derivation-manifest.md
4. Preserve the user's dimensional positions from ops/config.yaml
5. For user-modified skills with option (b): merge the user's customizations into the updated skill

5c. Update Version Tracking

Update the skill's frontmatter:

---