kb-preferences

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::

Modes

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

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 re