ckb/docs/decisions
Michał Kopeć 03ff809440 Improvement memory: attempts, expected outcomes, lesson context (D-0023)
Schema 1.8, after Google's Self-Improvement Memory paper (arXiv 2611.18856).
- Error book: one entry per recurring problem with every attempt, its
  expected and observed result and context; aliases on merge (ckb-lint §9).
- Decisions: expected_outcome, outcome, outcome_checked, ## Tried,
  append-only ## Outcome, an outcome-review procedure (ckb-decide); lint
  validates outcomes and closes a due review once outcome_checked >= review_on.
- Lessons: Context line, upstream lessons from linked/ in the session
  brief, adopt and merge rules (ckb-profile, session_start.py); ckb-init
  Step 8b carries lessons and problems into a new KB; ckb-upgrade b5.
- Deferred: a self-improvement loop over the template. Rejected: loading
  the whole record into context.
No VERSION change or changelog row: made on the merge from dev (D-0022).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 08:17:19 +01:00
..
0001-opt-in-file-based-kb-modules.md Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script 2026-09-24 20:45:09 +02:00
0002-software-module-design.md Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script 2026-09-24 20:45:09 +02:00
0003-python-runtime-with-degraded-fallbacks.md Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019) 2026-11-11 13:47:37 +01:00
0004-session-identity-from-git.md Template 1.14.0: session identity from git on workload, log and conversations 2026-10-16 09:45:22 +02:00
0005-session-titles-and-routines.md Template 1.16.1: agent picks the session title, first reply only announces it 2026-10-24 15:57:12 +02:00
0006-title-chosen-by-agent.md Template 1.16.1: agent picks the session title, first reply only announces it 2026-10-24 15:57:12 +02:00
0007-mcp-server-module.md Sync: local changes as of 2026-10-29T13:50:12Z 2026-10-29 14:50:12 +01:00
0008-document-templates.md Sync: local changes as of 2026-10-29T13:50:12Z 2026-10-29 14:50:12 +01:00
0009-session-start-in-one-call.md Sync: local changes as of 2026-10-29T13:50:12Z 2026-10-29 14:50:12 +01:00
0010-about-file.md Sync: local changes as of 2026-11-01T20:31:36Z 2026-11-01 21:31:36 +01:00
0011-session-start-hook.md Template 1.22.0: agent-knowledge release 1 2026-11-02 19:25:02 +01:00
0012-open-threads-not-a-status-file.md Template 1.22.0: agent-knowledge release 1 2026-11-02 19:25:02 +01:00
0013-kept-answers-and-secret-guards.md Template 1.22.0: agent-knowledge release 1 2026-11-02 19:25:02 +01:00
0014-schema-1-6-review-contradictions-tags-profiles.md Template 1.23.0: agent-knowledge release 2, schema 1.6 2026-11-02 20:06:02 +01:00
0015-section-index-and-access-log.md Template 1.24.0: release 3 batch 1, retrieval 2026-11-02 20:25:26 +01:00
0016-topic-summaries-and-consolidation.md Template 1.25.0: release 3 batch 2, consolidation and topics, schema 1.7 2026-11-02 20:30:26 +01:00
0017-capture-module-and-skill-evals.md Template 1.26.0: release 3 batch 3, capture module, skill evals, multi-agent docs 2026-11-02 20:44:05 +01:00
0018-share-mailbox-module.md Template 1.28.0: share module — mailboxes in a git channel (D-0018) 2026-11-11 13:31:51 +01:00
0019-two-dot-zero-drops-powershell.md Template 1.28.1: 1.x maintenance channel, major-version guard (D-0019) 2026-11-11 13:47:37 +01:00
0020-voice-module.md Template 2.2.0: voice and convert modules 2026-11-11 20:57:39 +01:00
0021-convert-module.md Template 2.2.0: voice and convert modules 2026-11-11 20:57:39 +01:00
0022-dev-branch-and-merge-versioning.md Branch flow: dev integration branch, version changes only on merge (D-0022) 2026-11-12 12:09:25 +01:00
0023-improvement-memory.md Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00
README.md Improvement memory: attempts, expected outcomes, lesson context (D-0023) 2026-11-18 08:17:19 +01:00

Template design decisions

Decision records about the template itself — why the Cascade KB is shaped the way it is. They use the same type: decision format as wiki/decisions/, but they live here, in the template layer, because:

  • wiki/decisions/ is content: a KB's own decisions about its own subject. ckb-reset may wipe it, and a fresh ckb-init starts it empty.
  • Skills, modules and docs cite these records. A template must not depend on pages the content layer is allowed to delete.

ckb-upgrade carries this folder along with the rest of the template layer.

Since D-0023 these records may carry expected_outcome, ## Tried and an appended ## Outcome, like any decision: write what a change should do before it ships, and check it when review_on comes. ckb-decide never writes here — it is not a place for a KB's project decisions.

# Decision
D-0001 Optional capabilities ship as file-based modules under .agents/modules/, installed on request
D-0002 The software module: gitignored src/ clones, two OpenSpec spec levels, hybrid vendoring
D-0003 Python stays the only scripting runtime; portable interpreter resolution, per-OS install guidance, a native fallback for the session-start check, degraded paths per skill (PowerShell half dropped by D-0019)
D-0004 The git identity is the session's author; one workload file per person per day; **Author:** on log entries and saved conversations
D-0005 A new session asks for its title first and waits (point 1 reversed by D-0006); routines are time-since-last actions in ckb.yaml, run after the user's request, with last_run committed
D-0006 The agent derives the session title from the first message and only announces it in one line; announce_title replaces ask_title
D-0007 The mcp module serves the KB over MCP: cascade-aware reads; remote writes limited to raw/inbox/ and retraction requests, each naming its KB and confirmed by the user, and removable only by the person who added the document; auth switched by one flag (none/token/oauth), server runs in place against its own clone
D-0008 Document templates are the user's Markdown files in root templates/, outside the cascade and the template layer; a comment per section is the agent's brief; ckb-document fills one into outputs/documents/, asking in one round and leaving TODO: lines instead of guesses
D-0009 Session start is one session_start.py call that says what to act on; wiki/index.md and the whole workload file are no longer read at start; a skill's ## Purpose says only what its description does not
D-0010 A root ABOUT.md, written by the owner, states what the KB holds (purpose, audience, scope, owners, sensitivity) and the README links to it; agents read it, never edit it; ingest checks scope against it; wiki/overview.md stays the agent's summary
D-0011 Session start can run as a per-machine, opt-in Claude Code SessionStart hook that injects the Rule E brief before the first message and after every compaction; Rule E stays the fallback
D-0012 "What is in flight" is collected from ### Open threads checkboxes in each person's workload notes, not a shared status page; threads close where they were opened
D-0013 Kept answers go to outputs/answers/ with fingerprinted sources and reach the wiki only through ingest; committed text is scanned for secrets and <private> spans, never auto-fixed, with a line-hash allowlist
D-0014 Schema 1.6: review/reviewed_by/reviewed_on (not status), tags against wiki/tags.md, a > CONTRADICTION: marker, protected ## Rules on project scopes; profiles in workload/profiles/ and explicit lessons via a new ckb-profile skill; claim-level validity deferred
D-0015 Retrieval gains a stdlib FTS5 section index (title/heading/tldr as a separate context column) cached in tmp/, fused at weight 1.0, with section anchors and token estimates; pages read go to a per-machine tmp/access.log that lint turns into demotion proposals only
D-0016 Schema 1.7: agent-built topic pages in wiki/topics/ with member-page digests as sources; a new ckb-consolidate skill writes proposals-only reports (topics, merges, links, stale, old log) and builds only approved topic pages
D-0017 Opt-in capture module (stdlib fetch, Wayback only over a failed/thinner page, agent tool fallback, untrusted marking, dedup at capture, yt-dlp with consent); structural skill evals with a prepare/check runner; multi-agent setup documented as untested
D-0018 Opt-in share module: KBs exchange documents through a git channel with one append-only mailbox per KB; received mail lands in raw/inbox/ (untrusted) and retractions in raw/retractions/; the git author must own the mailbox; handled messages are kept in a ledger in ckb.yaml
D-0019 Template 2.0.0 drops PowerShell; every script the template and its modules ship is Python (bash fallback and the container entrypoint named as exceptions); 1.x continues on a 1.x maintenance branch; ckb-upgrade never crosses a major version without asking
D-0020 Opt-in voice module: outgoing prose (kept answers, documents, reports, the project overview) is rewritten in a voice whose profile is a wiki page in wiki/voice/; settings in ckb.yaml; routed by the AGENTS.md block, not per-skill edits; frozen spans never change, vague claims are flagged rather than cut; writer: plugs in an external rewriting skill
D-0021 Opt-in convert module: Markdown becomes Word/ODT/PDF/HTML through pandoc in a named house style, a reference .docx in templates/styles/ built from a few settings or copied from a company .docx/.dotx; PDF and ODT go through LibreOffice from the styled .docx; KB links and frontmatter are cleaned in the copy; the Markdown stays the source
D-0022 All work lands on dev; VERSION changes only when dev is merged into experimental, test or main, a version keeps its number when promoted, main is merged back after a release, 1.x keeps its own fixes, and dev is not a channel
D-0023 Schema 1.8: error book per recurring problem with every attempt, its expected and observed result and context; decisions with expected_outcome checked at review and a ## Tried section; lessons with context, upstream lessons from linked/, lessons carried by ckb-init, merges with aliases; a self-improvement loop deferred until evals exist; loading the whole record unretrieved rejected