# ckb-upgrade — edge cases Reference material for the `ckb-upgrade` skill. Read when a run hits an unusual situation the main steps don't cover. - **`ckb.yaml` exists but has no `template:` block** — a KB created before this convention. Treat it as canonical repo on `main`, and add the block once an upgrade is actually applied. Don't write it on a check-only run. - **`ckb.yaml` names a branch that no longer exists upstream** (a dev branch that was merged and deleted) — report it with the list of branches that do exist, and ask which to move to. Don't guess: a deleted `experimental` may mean "its work is in `main` now" or "it was abandoned", and those lead to different answers. - **User asks to switch channel but declines every proposed change** — the switch didn't happen, so don't persist the new branch. They looked at another channel and chose not to take it; recording it would make the next run pull from a channel they rejected. - **Local `VERSION` is ahead of the target branch** — see Step 2. Report it as "ahead", never as "up to date", and treat any downgrade as an explicit, separately-confirmed operation. - **Template repo is this very repo** (the template project upgrading itself) — the comparison is between branches of one repo rather than between two repos. That's valid, and the usual flow is `experimental` → `test` → `main`; but say plainly that this is a self-upgrade, since the "local vs upstream" framing in the report reads oddly otherwise. - **No `VERSION` file locally** — treat local version as `0.0.0`; any real template version counts as newer. Mention in the report that this KB predates version tracking. - **No `kb_schema_version` in local `wiki/index.md` at all** — treat as unversioned/behind by default (Step 3), and say so plainly in the report rather than silently treating it as "version 0.0." - **This KB's own `origin` *is* the template repo itself** (i.e. this is the template project's own working copy) — the checks still work (they'll usually report "already up to date" on both fronts since you're comparing against yourself), but note this in the report so it's clear why an "upgrade" against your own remote looks like a no-op. - **Network/auth failure cloning the template repo** — report the raw error, make no changes on either track, and clean up any partial scratch clone. - **A "changed" template file's difference looks trivial** — still surface it for a decision; don't invent a heuristic for "safe to auto-take," since the cost of a wrong guess (silently discarding a real customization) is worse than one extra question. - **User declines every changed template file** — still add any pure-new files (nothing lost by doing so) and bump `VERSION`, since the KB genuinely is now aware it's on the newer template version even if it kept its own customized copies of specific files. - **User confirms the wiki migration but the wiki is very large** — process it in batches with progress updates rather than promising instant completion; it's fine for this to be the longest-running part of the skill. - **User declines the wiki migration** — still bump nothing under `wiki/`, including `kb_schema_version` — leave it exactly as found, so a future run of this skill still detects it as behind rather than silently considering it handled. - **A page's inferred `type` is ambiguous even after inspection** — ask the user directly for that page rather than guessing between two plausible types; don't let one uncertain page block backfilling the rest. - **Uncommitted local changes already present before running this skill** — proceed anyway (nothing here is destructive; every change lands as an ordinary working-tree diff, reversible with `git checkout`), but mention in the report that there was pre-existing uncommitted work, so the user knows the diff they're about to review isn't only from this upgrade. - **A skill folder was renamed or removed upstream** — don't delete the corresponding local folder automatically (it might still be in active use, or further customized locally); mention it in the report as "removed upstream, left in place locally" and let the user decide separately. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE) at the repository root, or .*