/upgrade

name: upgrade
description: Apply plugin knowledge base updates to an existing generated system. Consults the Ars Contexta research graph for methodology improvements, proposes skill upgrades with research justification. Never auto-implements. Triggers on "/upgrade", "upgrade skills", "check for improvements", "update methodology".
version: "1.0"
generated_from: "arscontexta-v1.6"
user-invocable: true
context: fork
model: opus
allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. **`ops/derivation-manifest.md`** — vocabulary mapping, platform hints

• Use `vocabulary.notes` for the notes folder name
• Use `vocabulary.note` / `vocabulary.note_plural` for note type references
• Use `vocabulary.reduce` for the extraction verb
• Use `vocabulary.reflect` for the connection-finding verb
• Use `vocabulary.reweave` for the backward-pass verb
• Use `vocabulary.verify` for the verification verb
• Use `vocabulary.rethink` for the meta-cognitive verb
• Use `vocabulary.topic_map` for MOC references

2. **`ops/config.yaml`** — processing depth, domain context

3. **`ops/derivation.md`** — derivation state and engine version

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:

| Category | Skills | Upgrade Mechanism | |----------|--------|-------------------| | **Generated skills** | /{vocabulary.reduce}, /{vocabulary.reflect}, /{vocabulary.reweave}, /{vocabulary.verify}, /ralph, /next, /remember, /{vocabulary.rethink}, /stats, /graph, /tasks, /refactor, /learn, /recommend, /ask | Runtime consultation with knowledge graph | | **Meta-skills** | /setup, /architect, /health, /reseed, /add-domain, /help, /tutorial, /upgrade | Plugin release cycle — update the plugin itself |

/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:

| Tier | Path | What It Contains | |------|------|------------------| | Methodology graph | `${CLAUDE_PLUGIN_ROOT}/methodology/` | All content — filter by `kind:` field (research/guidance/example) | | Reference docs | `${CLAUDE_PLUGIN_ROOT}/reference/` | WHAT — structured reference documents and dimension maps |

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 abo