ckb/docs/decisions/0020-voice-module.md
Michał Kopeć c57ddceffd Template 2.2.0: voice and convert modules
- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every
  prose file written under apply_to (outputs/answers, documents, reports,
  PROJECT-OVERVIEW) in a voice whose profile is a wiki page,
  wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode,
  profile, writer, apply_to, skip, chat); frozen spans never change, vague
  claims flagged not cut; `writer:` delegates to an external rewriting
  skill such as a personal ghost-writer. ckb-module writes a manifest's
  default_config into the entry's config:. Eval ckb-module/install-voice.
- 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and
  convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a
  house style in templates/styles/; unit tests and eval
  ckb-module/install-convert.

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

4.6 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Outgoing text gets a team voice through an opt-in `voice` module — profiles are wiki pages in wiki/voice/ (type voice-profile), settings live in ckb.yaml, an AGENTS.md block routes every prose file under apply_to through ckb-voice, frozen spans (frontmatter, Sources, Crux, quotes, Notes, code, numbers, names) never change, and an external rewriting skill can be plugged in with `writer:`. accepted 2026-11-11 Michał Kopeć .agents/modules/voice/, .agents/skills/ckb-module/SKILL.md, README.md, docs/MANUAL.md, docs/CHANGELOG.md 0.7 0.8 2026-11-11 365 high

D-0020 — A voice module for text that leaves the KB

Status: Accepted · Decided: 2026-11-11 · Deciders: Michał Kopeć

Context

Kept answers, documents from templates, consolidation reports and the project overview are read by people outside the KB, and they read like a model wrote them. Michał already runs a personal ghost-writer skill (banned AI vocabulary, rhythm, the abstraction trap, named voice profiles) in his home directory, and wanted the same pass on everything the KB sends out, with the profile kept in the KB itself so the team can maintain it.

Decision

  1. An opt-in module (D-0001 pattern), voice, with one skill, ckb-voice, and no script. Many KBs never publish anything, so the base pays no context for it.
  2. The profile is a wiki page, wiki/voice/<name>.md, type: voice-profile, with voice_of (team/person/third-party) and the usual ## Sources and protected ## Notes. It is knowledge the team reviews and corrects. A skill-folder file would be invisible to teammates and lost on a clone. Pages are created, and logged, by ckb-voice on the first calibration, never by the install.
  3. Settings live in ckb.yaml under the module's config: (mode, profile, writer, apply_to, skip, chat). ckb-module gains default_config in the manifest to write them on install and keeps edited values on a reinstall.
  4. The hook is the AGENTS.md block, not edits to each skill. The installed fragment says that any prose file written under apply_to goes through ckb-voice, whichever skill drafted it. ckb-document, ckb-retrieve, ckb-consolidate and ckb-project-summary stay unchanged, and a future skill writing to outputs/ is covered without a change.
  5. Wording only; content is frozen. Frontmatter, ## Sources, ## Crux, quotes and their attributions, ## Notes/## Rules, contradiction markers, <private> spans, code, paths, links, numbers, names and a template's headings are kept byte-for-byte and diffed before writing. Ghost-writer's rule to cut any claim that can't be made specific is inverted. Such a claim is kept and flagged, because in a KB its source may say more and dropping it changes the content.
  6. Profile precedence: named in the request, then voice: on the person's workload/profiles/ page, then the configured default. Never two profiles in one text.
  7. Pluggable writer. writer: can name another installed skill (a personal ghost-writer). ckb-voice still resolves the profile and runs the freeze check; when the skill is missing on a machine it falls back to its own rules.
  8. Out of scope by construction: wiki/, raw/, workload/, templates/, and the exports (outputs/okf/, outputs/starlight/), which mirror wiki pages rather than speak for anyone.

Alternatives considered

  • Depend on the user's home ghost-writer. It's not in the repo, so teammates wouldn't have it and the profile would live outside the KB. It's kept as an option through writer:.
  • Profiles in workload/profiles/ beside personal profiles. Those are per person and outside retrieval; a house voice is shared knowledge that deserves review status and a log.
  • A rewrite step in every output-writing skill. Four skills to edit now, and every future one to remember. The single AGENTS.md rule does the same job.
  • Rewrite wiki pages too. The wiki is evidence for retrieval and lint; voice belongs at the boundary, not in the store.

Consequences

  • One more page type, voice-profile, and one field, voice, additive on schema 1.7 with no version bump.
  • A rewrite costs a model pass per output file; mode: ask or off turns it down.
  • The freeze check runs in the agent, not in a script, so it is only as strict as the agent following it. A script diffing frozen spans is the natural follow-up if drift shows up.