ckb/.agents/skills/ckb-reset/SKILL.md
Michał Kopeć da2833abfe Sync: local changes as of 2026-11-01T20:31:36Z
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-01 21:31:36 +01:00

174 lines
9.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
name: ckb-reset
description: DESTRUCTIVE — empty this knowledge base back to a clean template, deleting every accumulated wiki page, decision record, graph edge, log entry and workload summary, then restoring the empty scaffold. Always inventories what would be destroyed and takes typed confirmation first. Use for "reset the wiki", "empty the wiki", "clean this KB out", or "wipe the knowledge base".
---
# Reset skill
## Purpose
The only skill that deletes knowledge on purpose. Everything below assumes
that getting this wrong destroys work that took a long time to accumulate,
and that "the user asked for it" is not enough on its own: people ask for
this in the wrong repo.
## Non-negotiable safety rules
1. **Never delete without an inventory shown first and an explicit confirmation
after it.** Not "proceed?" before you know the scale — the count is the thing
that makes the answer meaningful.
2. **Never touch the template layer.** `AGENTS.md`, `CLAUDE.md`, `.agents/`,
`.claude/`, `LICENSE`, `VERSION`, `README*`, `docs/`, `tests/`,
`.gitignore`, `ckb.yaml`, `.git/`. Those *are* the template.
3. **Never touch `src/`, `templates/` or `ABOUT.md`.** `src/` holds independent repositories
of code this skill has no business deleting. Not even with confirmation — tell
the user to delete them with `rm -rf` themselves if that's really what they
want. `templates/` holds the user's document templates, reusable across
resets and worth nothing to delete. `ABOUT.md` states what the KB is for,
which a reset of its content does not change; the owner edits it.
4. **Never run when the working tree is dirty**, unless the user overrides after
being told why. Uncommitted work is unrecoverable once deleted; committed work
is always recoverable from git.
5. **Never guess the scope.** If the user says "reset" without saying how far,
ask — don't assume the widest or the narrowest reading.
## How to run this skill
### Step 0 — Establish that git can undo this
Run `git status --short` and `git log --oneline -1`.
- **Dirty tree** — stop and report exactly what's uncommitted. Offer to commit
first ("Let me commit this as a restore point, then reset"), and only proceed
without committing if the user explicitly says the uncommitted work is
disposable. This is the single highest-value check in the skill: after a reset,
committed content is a `git checkout` away and uncommitted content is gone.
- **Not a git repository at all** — say so plainly and require a much more
explicit confirmation, because nothing here is recoverable. Recommend the user
copy the folder somewhere safe first.
- **Clean tree** — note the commit hash and tell the user it's the restore point.
Offer to tag it (`git tag pre-reset-<date>`), since a hash in a chat log is
easy to lose.
### Step 1 — Agree the scope
Present the tiers and let the user choose. Default to **Tier 1 only** if they
just said "reset the wiki" — the narrowest reading that satisfies the request.
| Tier | Contents | Default |
|---|---|---|
| **1 — Wiki knowledge** | Every page under `wiki/entities/`, `wiki/projects/`, `wiki/decisions/` (the `NNNN-*.md` records), `wiki/graph/edges.json` entries, and all log/overview/query-gap/error-book *entries* | **Yes** |
| **2 — Workload history** | Every `workload/*_summary.md` and `workload/ingest-reports/*` | Ask |
| **3 — Source material** | `raw/inbox/*`, `raw/archive/*`, `raw/retractions/*`, `raw/saved-conversations/*` | Ask — this is the user's original material and may exist nowhere else |
| **4 — Generated artifacts** | `outputs/*` | Ask — cheap to regenerate, usually safe |
| **5 — External sources** | `libs/*`, `linked/*` | Ask — **default no.** `linked/` holds symlinks to *other people's* KBs, and deleting a symlink target by accident is a real risk |
| **6 — Installed modules** | `ckb.yaml` (modules, conversation settings, routines) + module-installed skills + the marked blocks in `AGENTS.md`/`.gitignore` | Ask — **default no.** That's `ckb-module uninstall`'s job (and `ckb-routine --remove`'s), not this skill's |
For a template being prepared for distribution, tiers 1–4 are the usual answer.
**Say what each tier means in files, not just in names.** "Tier 3 deletes 48
files in `raw/archive/` including the original meeting recordings" is a sentence
that changes answers.
### Step 2 — Build and show the inventory
Count, don't estimate. For the chosen tiers:
```bash
find wiki/entities wiki/projects -name '*.md' ! -name 'index.md' | wc -l
ls wiki/decisions/[0-9]*.md 2>/dev/null | wc -l
grep -c '"from"' wiki/graph/edges.json 2>/dev/null || echo 0 # one `from` key per edge
ls workload/*_summary.md 2>/dev/null | wc -l
find raw/inbox raw/archive raw/retractions raw/saved-conversations -type f 2>/dev/null | wc -l
```
Present it as a table: what, how many, and — for anything irreplaceable — where
it came from. Call out explicitly:
- **Decision records**, by number and title. These are append-only by design and
represent reasoning that cannot be reconstructed; losing them is the most
expensive part of any reset.
- **`raw/archive/` material with no upstream**, if tier 3 is selected.
- **Anything with `retention: high`** in its frontmatter — the wiki's own signal
that it was meant to be kept.
Then state what will *survive*, in one line. That's as reassuring as the deletion
list is alarming, and it's what tells the user whether you understood the task.
### Step 3 — Take the confirmation
Ask for a typed phrase, not a yes:
> This will permanently delete **47 wiki pages, 12 decision records, 9 workload
> summaries and 128 graph edges**. Restore point: `491ca8a` (clean tree).
> Type **`reset the wiki`** to proceed, or anything else to cancel.
Accept only that phrase. A "yes", a "go ahead", or silence is **not** consent
here — the typed phrase exists precisely so the action can't be taken by reflex
or by an agent misreading agreement to something else in the conversation.
If the user modifies the scope in their reply, go back to Step 2 and re-inventory.
Never carry a confirmation across a scope change: they confirmed a number, and
the number moved.
### Step 4 — Delete, then restore the scaffold
Delete the agreed tiers. Then restore the empty scaffold **exactly as `ckb-init`
Step 8 defines it** — that skill is the single source of truth for what a clean
`wiki/` looks like, so read it rather than reconstructing the files from memory:
- `wiki/index.md` — routing table, infrastructure rows only, no entity rows.
**Keep `kb_schema_version` at its current value.** A reset empties content; it
does not roll back the schema contract.
- `wiki/overview.md` — the generic version, `last_updated` today.
- `wiki/log.md`, `wiki/decisions/log.md` — headers and explanation, no entries.
- `wiki/error-book.md`, `wiki/query-gaps.md` — headers, no entries.
- `wiki/entities/index.md`, `wiki/projects/index.md` — headers plus
placeholder notes.
- `wiki/graph/index.md` — header, placeholder, and the edge-vocabulary table
and conventions **verbatim**; that table is the contract every writing
skill validates against, not accumulated content, so a reset keeps it.
- `wiki/decisions/index.md` — header, placeholder, and the status-vocabulary
table **verbatim** (`ckb-decide` and `ckb-lint` both validate against it).
- `wiki/graph/edges.json` — `{"version": 1, "last_updated": "<today>", "edges": []}`.
- `.gitadd` placeholder files in any directory that would otherwise be empty, so
the structure survives in git.
Preserve directories even when empty. A reset KB must have the same shape as a
fresh one, or the next ingest starts by rebuilding scaffolding.
### Step 5 — Verify before reporting success
Do not report completion until you've checked it:
```bash
ls wiki/entities/ wiki/decisions/ wiki/projects/
<python> .agents/skills/ckb-lint/scripts/lint_report.py
git status --short
```
Lint should come back clean on a fresh scaffold. If it doesn't, the scaffold is
wrong — say so and fix it rather than declaring done. A reset that leaves a
malformed wiki is worse than no reset, because the damage is already unrecoverable
and now the structure is broken too.
### Step 6 — Report
State: tiers reset, counts deleted per tier, scaffold files restored, the restore
point hash (and tag, if one was made), lint result, and what was deliberately left
alone (`src/`, `templates/`, `ABOUT.md`, modules, template layer).
**Do not append a workload summary.** Rule D's session note would be the first
entry in a workload directory this skill just emptied, which defeats the purpose.
Say so in the report instead — this is a deliberate, one-off exception to Rule D,
and worth naming so it doesn't read as an oversight.
Finish with: the reset is on disk but not committed. `git checkout .` still undoes
everything until it is. That sentence is the last safety net, so don't omit it.
## Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.