ckb/.agents/skills/ckb-upgrade/references/edge-cases.md
Michał Kopeć 7863115b74 Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script
- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
  phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
  reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
  docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
  D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
  Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
  base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-24 20:45:09 +02:00

4.4 KiB

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 at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.