subjects / SUB-010

vault quality and company knowledge base.

open opened 2026-05-20 · touched 2026-05-20 · m5
#vault#knowledge-base#quality#documentation#infrastructure#m5

# SUB-010 — Vault Quality and Company Knowledge Base

> Paste SUB-010 into chat to context-shift here.

What it is

The vault is the single source of truth for Sett UX decisions, context, problems, and concepts. Currently it suffers from conflicts, irrelevant information, and soft/vague content. This is a two-track initiative to clean up the existing vault passively during daily work while also scheduling active quality audits, with the long-term goal of graduating the vault into a vetted company knowledge base that any employee (human or their AI) can consume for instant project understanding.

Why

Current state problems:
  • Vault contains conflicts, soft content, and vague assertions that don't help agents understand the WHY of decisions.
  • When Claude agents consume vault as context, they produce lower-quality outputs (e.g. Cosmo V2 dev presentation yesterday had noticeable slop).
  • Corrections Ishai makes in conversation stay in chat scrollback; they don't propagate back to the vault, creating persistent inconsistency.
  • New information enters vault without vetting, stacking on top of existing content rather than resolving conflicts.
Long-term vision:
  • The vault becomes a company resource, not just Ishai's working notes.
  • Humans and their AIs can plug in and immediately understand project state, goals, priorities, decisions, and rationale.
  • Think Wikipedia for agents: anyone at Sett can reference the vault and get instant context.
  • Contribution model: proposals get vetted before being added.

Audience

Phase 1 (now): Ishai + Claude agents consuming vault as context. Phase 2 (M5+): Entire Sett company, both humans and their AI tools.

Features (two-track approach)

Track 1 — Ongoing passive cleaning (while working)

Corrections and new information propagate immediately, not later.

| # | Feature | How | |---|---------|-----| | T1-F1 | Correction propagation | When Ishai corrects Claude in conversation, that correction updates the relevant vault file immediately (not just stays in chat) | | T1-F2 | Relevance vetting | New information entering vault is assessed for relevance before being stored (not just appended to everything) | | T1-F3 | Conflict resolution | When new info contradicts existing vault content, flag it + resolve instead of stacking both | | T1-F4 | Agent feedback loop | If an agent misunderstands vault content, that gap gets documented so future agents avoid the same trap |

Track 2 — Active audits (scheduled)

Periodic deep cleaning of old/stale content.

| # | Feature | Frequency | Trigger | |---|---------|-----------|---------| | T2-F1 | Vault quality sweep | End of each milestone | Milestone completion | | T2-F2 | Redundancy compression | Monthly | Manual or auto-scheduled | | T2-F3 | Staleness culling | Monthly | Manual or auto-scheduled | | T2-F4 | Conflict resolution audit | As-needed | When conflicts surface in conversation | | T2-F5 | Concept linkage check | Quarterly | Ensure related concepts cross-link properly |

Detailed feature specs

T1-F1 · Correction propagation

When Ishai says "that's wrong, here's what's actually true":

  • Claude identifies the relevant vault file(s).
  • Immediately updates that file with the correction.
  • Appends a dated note showing the correction came from Ishai's feedback.
  • Does NOT wait for end-of-session or batch-mode processing.

Example flow: 1. Ishai: "The milestone is actually 2026-05-25, not 2026-05-18." 2. Claude: identifies vault/00-Milestones.md, edits the date, appends [Updated 2026-05-20: Ishai corrected target date]. 3. Ishai continues working. Next context load sees the updated date.

T1-F2 · Relevance vetting

Before saving new info to vault, ask: "Is this actionable / durable / contextual? Or is it transient chat noise?"

Keep:

  • Decisions that affect how future work happens.
  • Context about user roles, problems, concepts that inform design.
  • Status that future sessions need.

Don't keep:
  • Task progress ("I finished the weekly mockup today").
  • In-flight conversation context ("we were discussing...").
  • Brainstorm ideas that didn't lead anywhere (unless marked as explicitly parked).
  • Duplicates of info already in the vault.

T1-F3 · Conflict resolution

When new info conflicts with vault content:

  • Flag the conflict explicitly in a comment or dated note.
  • Do not stack both versions. Resolve which is true.
  • If unsure, ask Ishai which version is canonical.
  • Link the superseded entry to the new one (see vault/98-References/glossary.md example: "Superseded by [link]").

T1-F4 · Agent feedback loop

When an agent misunderstands vault content and Ishai corrects it, log that gap.

Example:

  • Agent read vault/04-Concepts/Playable-as-Star.md and misunderstood what "star" means.
  • Ishai clarified. Claude appends a dated note to the concept doc: "[2026-05-20: Clarified for agents: 'star' refers to X, NOT Y. Common confusion.]"

This prevents the same misread from happening to a different agent later.

T2-F1 · Vault quality sweep

At the end of each milestone:

  • Dispatch the vault-summarizer agent to audit recent changes.
  • Remove stale items that have been superseded.
  • Compress redundant notes into single coherent entries.
  • Resolve conflicts from the milestone's work.
  • Result: a brief report + updated files.

Who triggers: Ishai manually, or auto on milestone completion? TBD.

T2-F2, T2-F3 · Redundancy compression + staleness culling

Monthly (or manual trigger):

  • Scan folders like vault/09-Notes/raw/ for orphaned brain-dumps.
  • Migrate actionable fragments to their proper vault homes.
  • Delete true ephemera (solved questions, outdated exploration notes).
  • Merge near-duplicate concept docs.

T2-F4 · Conflict resolution audit

Triggered when conflicts surface in conversation. Review the disputed vault section + surrounding context. Establish canonical version. Mark superseded content with a note pointing to the canonical entry.

T2-F5 · Concept linkage check

Quarterly audit: ensure related concepts have proper cross-links. Example: if a problem doc mentions a concept, the concept doc should link back to the problem. Bidirectional references improve agent navigation.

Specifications

File format and structure

Existing vault structure (unchanged):

  • vault/00-Action-Items.md — tasks and questions
  • vault/00-Milestones.md — milestone timeline
  • vault/01-Context/ — company + product context
  • vault/02-Users/ — roles and JTBD
  • vault/03-Cosmo-pages/ — per-page UX
  • vault/04-Concepts/ — design theses and mental models
  • vault/05-Problems/ — problem catalogue
  • vault/06-Meeting-notes/ — dated meeting notes
  • vault/07-Recommendations/ — quick wins
  • vault/08-Design-specs/ — surface specs
  • vault/09-Notes/ — raw brain-dumps (cleaned regularly)
  • vault/10-Activity-Log/ — daily activity log
  • vault/98-References/ — glossary, people, etc.

Dated notes for corrections and feedback: `` [Updated 2026-05-20: Ishai corrected X. See vault-entry-Y for context.] `

Cross-links when superseding: ` Superseded by: [link to new entry] `

Quality standards for vault entries

Before saving anything:

  • Is it actionable or contextual? Not transient progress.
  • Is the language clear? "We decided X" not "might be maybe-ish perhaps X".
  • Does it conflict with existing content? If yes, resolve before saving.
  • Is there a source or rationale? If it's a decision, who decided and why.

Company knowledge base graduation (Phase 2)

Once vault content is vetted and conflict-free, it can graduate to external-facing company docs:

  • Format: same markdown, same structure (easier for agents to migrate context).
  • Audience: any Sett employee, plus their AI tools.
  • Contribution model: proposals enter a staging area, get reviewed by Ishai + relevant domain owner (e.g. dev + design for a technical decision), then move to canonical company vault.
  • Sync cadence: weekly or per-milestone.

Scope

v1 (ongoing)

  • T1-F1, T1-F2, T1-F3 applied during daily work (now).
  • T2-F1 at milestone completion (M1, then M2, then M3...).
  • Manual trigger for T2-F2 through T2-F4 as needed.

v2 (M5, post-MVP)

  • Auto-scheduled vault audits (T2-F2, T2-F3) once per month.
  • Company knowledge base staging area + contribution model.
  • Phase-2 rollout plan.

Decisions made

  • 2026-05-20. Two-track approach: passive daily cleaning + scheduled audits. (See rationale above.)
  • 2026-05-20. Corrections propagate immediately (same session), not batched. Keeps vault in sync with decisions made in conversation.
  • 2026-05-20. Vault stays single-source-of-truth for Ishai + agents. Company KB is Phase 2, derived not primary.

Open threads

  • Verification status mechanism (2026-06-01): the concrete primitive SUB-010 was missing is a per-doc verified: frontmatter flag (unverified / reviewing / verified / stale-verified). Specced in the Studio Documentation section: vault/08-Design-specs/studio/_documentation.md + _tech-documentation.md. Enables publish-gate, "use verified only" retrieval mode, and the vetted-vs-raw separation needed for Phase-2 KB graduation. SUB-010 owns the strategy; that spec owns the mechanism.
  • Define exact trigger for T2-F1 (milestone end, manual, both?) — who calls vault-summarizer
  • Define staleness thresholds — what age makes a note a candidate for culling
  • Decide conflict-resolution escalation — when does Ishai get asked vs Claude resolves
  • Design company KB contribution model — review + approval workflow, staging area structure
  • Automate vault quality dashboard — show stale items, conflicts, age distribution, etc.
  • Agent training — brief all agents on how to use the vault (what to trust, what to flag as soft)

Status

| Date | What happened | |------|---------------| | 2026-05-20 | Subject created. Two-track approach defined. T1 features to apply during daily work starting immediately. T2 audits to begin at M1 completion (2026-05-11 or retroactively). |

Next milestone: Apply T1 practices in real time during V2 polish + Apollo work. Schedule first T2 vault sweep at end of M1 (2026-05-11+) retroactively or at M2 completion (2026-05-25).

Raw refs

  • Concept doc: (to be created: vault/04-Concepts/vault-quality.md)
  • Activity log: vault/10-Activity-Log/
  • Studio site subject display: SUB-001
  • Vault structure reference: .claude/rules/vault-structure.md`
  • Correction and vetting patterns: see CLAUDE.md "Append, don't overwrite" rule
context-shift paste this id into chat to resume on this thread