ckb/.agents/skills/ckb-consolidate/SKILL.md
Michał Kopeć 221a6a29b1 Template 1.25.0: release 3 batch 2, consolidation and topics, schema 1.7
- F13 new skill ckb-consolidate with consolidate.py: a proposals-only
  report in outputs/reports/ (topic clusters and their state, merge
  candidates, missing links, stale pages, old log entries by month);
  never edits a page, never rewrites the log
- F15 topic pages (type: topic) in the new wiki/topics/, built only on
  approval, with member-page digests as ## Sources so lint flags drift;
  ckb-retrieve routes "overall" questions to wiki/topics/index.md first
- Schema 1.7 (D-0016): ckb-upgrade b4, ckb-init and ckb-reset know
  wiki/topics/; ckb-routine suggests a fortnightly Consolidate --confirm

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:30:26 +01:00

128 lines
4.8 KiB
Markdown

---
name: ckb-consolidate
description: Propose wiki maintenance without touching a page — topic clusters and their summary pages in wiki/topics/, merge candidates, missing links, stale pages, old log entries — as a report in outputs/reports/, then build or refresh the topic summaries the user approves. Use for "consolidate", "consolidate the wiki", "what could be merged", "build topic summaries", "refresh the topics", or a scheduled consolidation routine.
---
# Consolidate skill
## Purpose
A second pass over what ingest built, done apart from answering questions
(Letta's sleep-time idea, Beads' memory decay). The report proposes and the
user decides. The only pages this skill writes are topic summaries in
`wiki/topics/`, and only those the user approved.
Untouchable here: `## Notes`, `## Rules`, `## Crux` quotes, decision
records, and the substance of every page outside `wiki/topics/`. An approved
merge or link goes through the skill that owns that change (`ckb-ingest`
edits, `ckb-lint` fixes, `ckb-decide` supersession), never through this one.
## How to run this skill
### Step 1 — Run the report
```bash
<python> .agents/skills/ckb-consolidate/scripts/consolidate.py --write
```
Resolve `<python>` per "Scripts and the Python Runtime" in `AGENTS.md`. It
writes `outputs/reports/YYYY-MM-DD_consolidation.md` and changes nothing in
`wiki/`:
- **Topics** — clusters of related pages: a project scope's members, pages
sharing a tag, then linked groups of three or more. Each one shows whether
`wiki/topics/<name>.md` is `missing`, `current` or `outdated` (a member
changed, joined or left).
- **Merge candidates** — two pages of one type whose title and `tldr` say
nearly the same thing. Read both before proposing anything; similar words
are not the same claim.
- **Missing links** — pages that cite the same sources but don't link to each
other.
- **Stale or drifted** — lint's freshness and source-drift findings.
- **Log older than 90 days** — entry counts by month. The log itself is
never rewritten (Rule B). If the user wants a summary of old work, write it
in the report, not in the log.
Without Python, say so and do a reduced pass by hand: list `wiki/projects/`
scopes as topic candidates, and use `rg` to find pages sharing a
`raw/archive/` source.
### Step 2 — Present it and take decisions
Summarise the report in a few lines: how many proposals of each kind, then
the ones worth acting on first (outdated topics, drifted pages). Ask which to
act on. A merge, a link or a refresh is handed to its owning skill with what
the report found. Nothing is applied without a yes.
### Step 3 — Build or refresh an approved topic page
A topic page answers "what does the KB say overall about X" in one read. It
is synthesis from the member pages, not new knowledge: every claim on it must
already be on a member page.
```markdown
---
type: topic
tldr: One sentence on what the KB holds about this topic.
review: draft
last_updated: YYYY-MM-DD
freshness_window_days: 90
retention: medium
---
# <Topic name>
## Summary
<What the members say together: the main facts, how they relate, open
questions. Where members disagree, say so and name both; never resolve it
here.>
## Members
- [[entities/x]] / [X](/wiki/entities/x.md) — what this page adds, one line
## Sources
- `wiki/entities/x.md` — sha256:3f9a2c1e (checked YYYY-MM-DD)
## Notes
<!-- Yours. Never rewritten by any skill. -->
```
`## Sources` lists every member page with its digest, taken from the report
(`--json` gives `digests`) or `sha256sum <page> | cut -c1-8`. Lint check 12
then flags the topic as soon as a member changes, and the next report marks
it `outdated`.
On a refresh, rewrite `## Summary`, `## Members` and `## Sources`, keep
`## Notes` byte for byte, set `last_updated`, and set `review: needs_update`
if it was `reviewed`. Add or update the row in `wiki/topics/index.md` and log
every topic page under Rule B.
### Step 4 — Report and remind
Name the report's path, what was approved, and the topic pages written.
Close with the usual reminder to review and say "sync changes".
## As a routine
Consolidation suits a routine that asks first:
```bash
<python> .agents/skills/ckb-routine/scripts/routines.py --add --name consolidate --do "Consolidate" --every 14d --confirm
```
With `confirm: true` the session asks at the end of the reply, and a yes
runs Step 1 and Step 2. A routine never builds topic pages on its own.
## Edge cases
- **A page in several clusters** (a scope and a tag) — normal; it is a
member of each topic.
- **A cluster with an existing topic under another name** — propose renaming
the topic page to the cluster name. Never keep two topic pages for one
cluster.
- **A topic whose cluster disappeared** — propose `superseded_by` or
removal. Removing a topic page is a logged delete, done only on a yes.