migrate-recipe

paper-wiki Migrate Recipe

Overview

When paper-wiki's bundled recipe templates are updated (e.g. v0.3.17 dropped foundation model from biomedical-pathology to stop matching every ML paper), personal recipe copies generated by the setup wizard stay on the old keyword set. This SKILL surgically applies the known migrations — removing stale keywords, adding replacements — without touching the user's vault path, API keys, auto_ingest_top, custom topics, or any other recipe field.

The underlying runner (paperwiki.runners.migrate_recipe) is LLM-free: it diffs two keyword lists and applies the changes. No network calls. The original file is always backed up before any write (<recipe>.bak.<YYYYMMDDHHMMSS>), so the user can restore manually if needed.

When to Use

• The user types /paper-wiki:migrate-recipe.
• Setup SKILL Branch 1 detects stale keywords (e.g. foundation model in biomedical-pathology) and the user selects "Migrate recipe to v0.3.17+ keywords".
• The user reports that unrelated papers (e.g. remote-sensing papers) are showing up in their biomedical-pathology bucket.
• After upgrading from a pre-v0.3.17 install and noticing stale relevance hits.

Do not use when the user wants to add entirely new topics or change the vault path — that routes to /paper-wiki:setup ("Edit one piece").

Process

Step 1 — Locate the recipe

Default path: ~/.config/paper-wiki/recipes/daily.yaml. If $PAPERWIKI_CONFIG_DIR is set, look there instead. Confirm the file exists; if not, surface a clear error and suggest /paper-wiki:setup.

Step 2 — Dry-run first

Run this exact bash to invoke the migrate-recipe runner in dry-run mode and show the user what would change. The export PATH=... line is mandatory — fresh-install users may not have ~/.local/bin on PATH yet (D-9.34.6).

source "$HOME/.local/lib/paperwiki/bash-helpers.sh" 2>/dev/null || {
    echo "ERROR: paper-wiki bash-helpers missing at ~/.local/lib/paperwiki/bash-helpers.sh." >&2
    echo "  Fix: exit Claude Code and re-open — the SessionStart hook installs the helper." >&2
    echo "  Persistent failures: ~/.local/lib/ may be unwritable; re-run \$CLAUDE_PLUGIN_ROOT/hooks/ensure-env.sh." >&2
    exit 1
}
paperwiki_ensure_path
paperwiki migrate-recipe ~/.config/paper-wiki/recipes/daily.yaml --dry-run

Parse the JSON output. If applied_changes is empty, tell the user their recipe is already up to date (no action needed) and exit.

Step 3 — Surface the diff and ask for confirmation

If applied_changes is non-empty, format the diff clearly:

Proposed changes to daily.yaml:

  biomedical-pathology:
    remove: foundation model
    (no additions)

A backup will be created at daily.yaml.bak.<timestamp>.

Use AskUserQuestion to confirm:

AskUserQuestion call:

• question: "Apply this keyword migration to your personal recipe?"
• header: "Migrate?"
• multiSelect: false
• options:
  1. label: "Yes, apply" description: "Update daily.yaml in place. Backup created automatically."
  2. label: "No, keep stale" description: "Leave the recipe unchanged. You can re-run this SKILL later."
  3. label: "Show me more detail" description: "Print the full before/after keyword lists for each topic."

Note: Claude Code automatically appends a Cancel option.

If the user chooses "Show me more detail": read the recipe YAML and print the current keywords for each affected topic next to the proposed removals/additions. Then re-ask.

Step 4 — Apply the migration

Run this exact bash to invoke the migrate-recipe runner in apply mode:

source "$HOME/.local/lib/paperwiki/bash-helpers.sh" 2>/dev/null || {
    echo "ERROR: paper-wiki bash-helpers missing at ~/.local/lib/paperwiki/bash-helpers.sh." >&2
    echo "  Fix: exit Claude Code and re-open — the SessionStart hook installs the helper." >&2
    echo "  Persistent failures: ~/.local/lib/ may be unwritable; re-run \$CLAUDE_PLUGIN_ROOT/hooks/ensure-env.sh." >&2
    exit 1
}
paperwiki_ensure_path
paperwiki migrate-recipe ~/.config/paper-wiki/recipes/daily.yaml

Parse the JSON output. Confirm:

• backup_path — show the backup location to the user.
• applied_changes — confirm each topic that was updated.

Step 5 — Report

Tell the user:

• Which keywords were removed / added per topic.
• Where the backup lives (so they can restore if they change their mind).
• Suggested next step: run /paper-wiki:digest to verify the updated recipe no longer routes unrelated papers into the migrated bucket.

Common Rationalizations

Excuse	Why it's wrong
"I'll skip the dry-run — the change is small."	The dry-run is the only way to confirm the migration matches expectations before touching the file. It costs nothing and prevents surprises. Always dry-run first.
"I'll skip the backup — there's a version in git."	Not every user uses git for their config. The timestamped backup is the safety net. The runner creates it automatically; do not skip it.
"I'll remove all keywords that don't match the bundled template — more thorough."	Wrong. The runner only removes keywords explicitly listed in the migration table. User-added keywords are always preserved. Never broaden the scope beyond the declared migration.
"The recipe is small — I'll just re-write it manually to match the template."	Manual rewrites lose user customisations (custom topics, vault path, API key indirection). Use the runner's surgical migration; do not overwrite the whole file.

Red Flags

• backup_path is null in the runner output after a non-dry-run with applied_changes non-empty → STOP. The backup step must have failed. Do not proceed; check disk space and permissions.
• Runner exits non-zero → surface the error message from stderr and suggest running with --verbose for details.
• User's custom 5th topic keywords are missing after migration → STOP. The runner only removes declared stale keywords; custom keywords must survive. Restore from backup and report the issue.

Verification

• applied_changes in the runner output lists only the expected keyword removals (e.g. foundation model from biomedical-pathology).
• User-added keywords (custom topics, extra keywords in existing topics) are present in the updated recipe.
• backup_path points to a file that exists on disk.
• Re-running the migration on the already-updated recipe produces applied_changes: [] (idempotent).
• The next /paper-wiki:digest run no longer routes unrelated papers into the migrated topic bucket.