kb-preferences

name	kb-preferences
description	Use when user wants to view, update, reset, or audit report preferences stored in vault kb.yaml. Triggers on '/kb-preferences', 'update report prefs', 'change report style', 'my preferences', or when a passive reflection step in another skill needs to propose preference updates.
user-invocable	true
allowed-tools	Read, Write, Edit, Glob, Bash, AskUserQuestion

Overview

Manage the report_preferences: block in the vault's kb.yaml. This is a free-text preference store — each field is a prose instruction string that research-report, kb compile, and kb query read when generating output. Factory defaults come from plugins/kb/references/report-style-guide.md, which is consulted only at init / reset time.

Update path in three places:

1. User runs /kb-preferences ... explicitly — this skill.
2. User hand-edits kb.yaml — no skill involvement.
3. Another skill's reflection step proposes updates after finishing a report — that skill calls into this one.

Every write confirms with the user first and logs the change to .meta/_preference_history.md. The kb.yaml and the history file are the only two places state lives.

Prerequisites

• kb.yaml exists at the vault root. If missing, tell the user to run kb-init and stop.
• plugins/kb/references/report-style-guide.md exists (plugin-shipped; should always be present).
• .meta/_preference_history.md exists. If missing, create it with the template below before any write.

Fields managed

All fields under kb.yaml → report_preferences::

Field	What it controls
audience	Who the report is written for; framing, polish, hedging
register	Tone, sentence style, vocabulary
depth	Items-covered × per-item-depth tradeoff
code_handling	Inline vs linked vs walkthrough, scaled by codebase count
diagrams	ASCII / mermaid / prose / tables
self_containment	Glossing, mini-profiles, no appendix deferrals
citations	arXiv-style rigor vs loose references
argument_iteration	Draft → advisor → verifier loop + "where this might be wrong"
notes	Free-form addendum; grows via reflection

Modes

The skill detects mode from user invocation. Parse the arguments after /kb-preferences:

Invocation	Mode	Action
/kb-preferences (bare)	interactive	Show current prefs, ask what to update
/kb-preferences init	init	Re-run the 5 init questions, regenerate all fields from style-guide + user answers
/kb-preferences update <field>	update-one	Focus on one field; re-ask matching question or accept free-text
/kb-preferences add-note "..."	add-note	Append the quoted string as a new line/paragraph under notes:
/kb-preferences reflect	reflect-now	Run the reflection step against the current conversation explicitly
/kb-preferences review	review	Print current report_preferences: block read-only
/kb-preferences reset <field>	reset-one	Copy factory default for one field; confirm first
/kb-preferences reset-all	reset-all	Full reset to defaults; confirm first
/kb-preferences history	history	Print .meta/_preference_history.md

Mode: interactive (bare invocation)

1. Read kb.yaml report_preferences: section.
2. If missing, tell user to run /kb-preferences init first and stop.
3. Print each field with a truncated preview (~80 chars, "..." if longer).
4. AskUserQuestion: "Which field would you like to update?" with the 9 field names + "none / cancel" as options.
5. If a field picked, delegate to update-one mode for that field.

Mode: init

Same flow as kb-init §5.5. Ask the 5 open-ended questions (see kb-init SKILL.md for the exact phrasing):

1. Primary reader → audience
2. Style preferences → register
3. Depth vs breadth → depth
4. Code handling → code_handling
5. Anything else → notes (+ opportunistic tweaks to diagrams / citations if signaled)

For each answer, open plugins/kb/references/report-style-guide.md, pick the best-matching variant, optionally weave in user phrasing, write to the corresponding field in kb.yaml.

Fields not asked at init (self_containment, citations, argument_iteration) get their ### Default variants unchanged unless question 5 signaled a change.

Confirm the full assembled block with the user before writing. Show the block, ask "Write this to kb.yaml? [y/n/edit]". On edit, let them hand-revise the text.

Log each changed field to .meta/_preference_history.md.

Mode: update-one

1. Argument is the field name. Validate it's one of the 9 known fields. If notes, prefer add-note mode.
2. Show the current value of that field to the user.
3. AskUserQuestion the matching init question for that field.
4. Consult the style guide, pick a variant, weave in user phrasing.
5. Show the new proposed value, confirm with user ("Write? [y/n/edit]").
6. On confirmation, write to kb.yaml and log to history.

Mode: add-note

1. Argument is a quoted string.
2. Read current notes: field.
3. Append the string as a new bullet (or paragraph if multi-sentence).
4. Confirm with user, write, log.

Mode: reflect-now

Explicit reflection against the current conversation. Used when the user wants to force a pass.

1. Scan the conversation for preference signals (see Reflection Protocol below).
2. If signals found, propose updates with diffs.
3. Confirm, write, log.

If no signals, say so and exit.

Mode: review

Read-only. Print the full report_preferences: block, each field shown in full (no truncation). No changes.

Mode: reset-one

1. Argument is the field name.
2. Open plugins/kb/references/report-style-guide.md, pull the ### Default variant for that field.
3. Show diff between current value and factory default.
4. AskUserQuestion: "Reset this field to factory default? [y/n]".
5. On yes, write to kb.yaml, log reset-one trigger in history.

Mode: reset-all

1. Confirm loudly: "This will replace all 9 fields with factory defaults and re-run the 5 init questions. Continue? [y/n]".
2. On yes, behave like init mode.
3. Every field change is a separate history log entry with trigger reset-all.

Mode: history

Print .meta/_preference_history.md. If missing, say "No history yet" and create the file per the template below.

Reflection Protocol

Called in two situations:

• This skill's reflect-now mode (user explicit)
• The reflection step at the end of research-report, kb compile, or kb query

Algorithm:

1. Scan the conversation for signals across these categories:

   • Corrections: user pushed back on output ("no, make it plainer", "drop the academic connectives", "you're using too much jargon")
   • Silent-accept signals: user accepted a non-obvious style choice without comment → validation of that choice
   • Explicit feedback: user said "I liked X" or "next time, do Y"
   • Meta-comments: "for every work I do, remember X"

2. Map each signal to a specific report_preferences field.

   • Word-level complaints → register
   • Content coverage / depth complaints → depth
   • Code handling complaints → code_handling
   • Citation rigor requests → citations
   • Diagram preferences → diagrams
   • Self-containment feedback → self_containment
   • Argument validation requests → argument_iteration
   • Target-reader hints → audience
   • Anything else that's a one-off preference → notes

3. Propose concrete edits, not abstract advice. For each signal, show:

   Signal: "<short paraphrase of what user said or did>"
   Field: <field_name>
   Current (excerpt): "<~60 chars>..."
   Proposed (excerpt): "<~60 chars with the change>..."
   

4. Present proposals as a numbered list and ask:

   Apply these changes to kb.yaml?
     [a] all   [n] none   [e] edit each one   [1,3] just those
   

5. On apply: write accepted changes to kb.yaml, append entries to .meta/_preference_history.md.

6. If no signals found: skip silently unless mode is reflect-now (in which case say "no signals detected").

Signal strength rules

• Don't propose a change for a single offhand remark. Require either (a) explicit "remember this" phrasing, (b) two occurrences of the same feedback, or (c) the feedback is directly tied to the report just produced.
• Don't propose contradictory changes. If the current field already captures the feedback, skip.
• Don't propose style-guide lists (e.g., don't bloat register with 40 forbidden words from one session). Keep field text under ~400 words; if a field is bloating, start a new notes bullet instead.

.meta/_preference_history.md format

---
title: "Preference Change History"
updated: YYYY-MM-DD
---

# Preference Change History

Append-only log of changes to `report_preferences` in `kb.yaml`.

| Date | Field | Trigger | Old → New |
|------|-------|---------|-----------|
| 2026-04-21 | register | user (/kb-preferences update) | "Plain..." → "Plain and very short..." |
| 2026-04-22 | notes | reflection after /research-report | (empty) → "Per-item profiles max ~150 words" |

Triggers to use in the Trigger column:

• user (/kb-preferences <mode>) — explicit user invocation
• user (init) — first-time setup during kb-init
• reflection after <skill> — reflection step from research-report / kb compile / kb query
• reset-one / reset-all — factory default restore
• hand-edit detected — if future tooling notices the user directly edited kb.yaml (not implemented now; reserved trigger)

For each write:

• Truncate old and new values to ~60 chars; use ... if truncated.
• If a field previously did not exist, old value is (unset). If a field is cleared, new value is (empty).
• Update the updated: frontmatter to the current date.

Common Mistakes

• Forgetting to confirm before writing. Every write path confirms. No silent updates except no-op exits when no signal is detected.
• Treating notes as a dumping ground. Apply the signal to the specific field if one fits; only fall back to notes if no field matches.
• Bloating fields indefinitely. Fields cap at ~400 words; past that, start a notes bullet instead.
• Reading plugins/kb/references/report-style-guide.md at report-generation time. That file is only consulted by this skill and kb-init, at init / reset time. Report-generating skills read kb.yaml.
• Renaming kb.yaml fields. The field names are a contract with the other skills (research-report, kb). Do not rename.
• Parsing the free-text field values. They're prose instructions for the next report, not keyword lists.
• Skipping history logging. Every approved change goes in .meta/_preference_history.md. If the file is missing, create it from the template.