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

75 lines
4.4 KiB
Markdown

# 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 <http://www.apache.org/licenses/LICENSE-2.0>.*