ckb/.agents/skills/ckb-reset/SKILL.md
Michał Kopeć 1dd18f2c99 Template 1.12.0: ckb-add-conversation, ideas/ scratch folder
- New skill ckb-add-conversation: on request, copies the session's Claude
  Code transcript (JSONL) into raw/saved-conversations/<date>/ with a
  readable Markdown rendering and an index.md; answers "did we discuss X"
  from those files. Saved conversations stay outside retrieval and ingest.
- AGENTS.md: directory contract, cascade note, routing row, disambiguation,
  Rule E session-end ask (save only on a yes).
- ckb-retrieve, ckb-ingest, ckb-reset (tier 3), ckb-init know the folder.
- Docs, both READMEs, CHANGELOG, VERSION; smoke test renders a fixture
  transcript against a golden file.
- .gitignore: ideas/ local scratch folder for template ideas.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-16 08:27:22 +02:00

9 KiB
Raw Blame History

name description
ckb-reset 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

A KB that also serves as the template for other KBs accumulates content that shouldn't ship with it — decisions made about this project, workload summaries, entity pages, graph edges. This skill returns it to the shape ckb-init creates: same structure, same schema, no knowledge.

It is the only skill in this KB that deletes knowledge on purpose. Everything below is written on the assumption 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/. Those are independent repositories holding 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.
  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 Ask
3 — Source material raw/inbox/*, raw/archive/*, 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 + module-installed skills + the marked blocks in AGENTS.md/.gitignore Ask — default no. That's ckb-module uninstall's job, 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:

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/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:

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/, 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. Read that file when a run hits something the steps above don't cover; don't load it otherwise.