Michał Kopeć
0c06cb64ab
Commit all in-flight work — ckb-module and ckb-reset skills, the .agents/modules/ scaffold, OPENSPEC docs, decision records D-0001 and D-0002, graph edges and workload summaries — so the reset that follows is fully recoverable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
198 lines
10 KiB
Markdown
198 lines
10 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, workload summary and (on request) raw/outputs material, then restoring the empty scaffold that `ckb-init` would create. Use when the user says "reset the wiki", "empty the wiki", "clean this KB out", "make this a clean template", "wipe the knowledge base", or wants to turn a working KB back into a distributable template. Always inventories what would be destroyed and takes explicit confirmation before deleting anything. Never touches the template layer (AGENTS.md, skills, modules, docs) or `src/`.
|
||
---
|
||
|
||
# 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.
|
||
|
||
## Trigger phrases
|
||
|
||
- "reset the wiki" / "empty the wiki" / "wipe the knowledge base"
|
||
- "clean this KB out" / "make this a clean template"
|
||
- "turn this back into a template" / "strip the content but keep the structure"
|
||
|
||
## 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*`, `MANUAL*`, `OPENSPEC*`,
|
||
`.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/*` | 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:
|
||
|
||
```bash
|
||
find wiki/entities wiki/projects -name '*.md' ! -name 'index.md' | wc -l
|
||
ls wiki/decisions/[0-9]*.md 2>/dev/null | wc -l
|
||
python3 -c "import json;print(len(json.load(open('wiki/graph/edges.json'))['edges']))"
|
||
ls workload/*_summary.md 2>/dev/null | wc -l
|
||
find raw/inbox raw/archive -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`, `wiki/graph/index.md` —
|
||
headers plus placeholder notes.
|
||
- `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/
|
||
python3 .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
|
||
|
||
- **Already clean** — say so and change nothing. Don't rewrite identical scaffold
|
||
files to look busy.
|
||
- **Run in a KB that is not a template** — this skill can't tell the difference,
|
||
so if the wiki holds substantial content (say, 50+ pages or any decision
|
||
records), name that in the confirmation: "This KB has 12 decision records —
|
||
templates don't usually have those. Are you in the right repository?" Ask once;
|
||
don't refuse if they confirm.
|
||
- **`linked/` symlinks** — never follow them when deleting. `rm -rf linked/foo`
|
||
where `foo` is a symlink to another KB is catastrophic and silent. Remove the
|
||
*link*, never its target, and prefer leaving tier 5 alone.
|
||
- **Partial failure mid-delete** — stop, report exactly what was and wasn't
|
||
deleted, and point at the restore point. Don't continue on the theory that
|
||
finishing is tidier.
|
||
- **User asks to reset "everything including the skills"** — that's not a reset,
|
||
it's deleting the KB. Say so and point at `ckb-init` for a fresh one elsewhere.
|
||
- **Module installed** — module-created page types (`repository`, `component`,
|
||
`spec`) are wiki content and reset with tier 1. The module itself stays
|
||
installed unless tier 6 was chosen.
|
||
|
||
---
|
||
|
||
*Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE)
|
||
at the repository root, or <http://www.apache.org/licenses/LICENSE-2.0>.*
|