174 lines
9.1 KiB
Markdown
174 lines
9.1 KiB
Markdown
---
|
||
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.
|