ckb/docs/decisions/0016-topic-summaries-and-consolidation.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

63 lines
3.1 KiB
Markdown

---
type: decision
tldr: Schema 1.7 adds agent-built topic pages in wiki/topics/ (type topic) whose ## Sources are member-page digests, so lint flags them when a member changes; a new ckb-consolidate skill writes a proposals-only report (topics, merges, missing links, stale pages, old-log digest) and builds only the topic pages the user approves.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, wiki/index.md, wiki/topics/index.md, .agents/skills/ckb-consolidate/, .agents/skills/ckb-retrieve/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-init/, .agents/skills/ckb-reset/, .agents/skills/ckb-routine/
confidence: 0.7
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0016 — Topic summaries in wiki/topics/, and a consolidation report
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Release 3, batch 2: F13 (a background consolidation pass) and F15 (topic
summaries for whole-KB questions, after Microsoft GraphRAG's community
reports). Both look across the wiki for structure no single ingest sees. Both
risk the same failure: an agent rewriting pages on its own judgment while
nobody is watching.
## Decision
1. **Topics live in `wiki/topics/`** (the user chose this over `outputs/`),
as `type: topic` pages with `## Summary`, `## Members`, `## Sources` and a
protected `## Notes`. Their `## Sources` are the member pages with
digests, so lint check 12 flags a topic when any member changes. This is
schema **1.7**: additive, a new optional directory and type.
2. **A topic is a map, not evidence.** Every claim on it must already be on a
member page, and retrieval follows its sources before grounding an
answer. "What does the KB say overall about X" questions route to
`wiki/topics/index.md` first.
3. **One skill, `ckb-consolidate`, for both.** Its script clusters pages
(project scope members, then shared tags, then linked groups of three or
more) and writes a report of proposals: topics missing or outdated, merge
candidates, missing links, stale pages, and old log entries by month. It
never edits a page. The skill builds only the topic pages the user
approves; merges and links go to the skills that own those edits.
4. **The log is never compacted.** Rule B's log stays complete; the report
may summarise old entries, but it doesn't rewrite them.
5. **As a routine, it asks first** (`--every 14d --confirm`) and never builds
topics unattended.
## Alternatives considered
- **Topics in `outputs/`** — kept out of the schema, but out of retrieval's
first pass too; rejected by the user.
- **Two skills** (consolidate, topics) — one more always-loaded
description for work that shares one scan.
- **Auto-applying safe proposals** (missing links) — rejected: proposals
accumulate trust only if a person sees them.
## Consequences
- A busy topic is flagged often, because every member edit drifts it. That
is intended: the summary may no longer hold.
- Clustering is deliberately simple and explainable, not community
detection; the report says why each cluster exists.