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

3.1 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Schema 1.7 adds agent-built topic pages in wiki/topics/ (type topic) whose accepted 2026-11-02 Michał Kopeć 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/ 0.7 0.8 2026-11-02 365 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.