vv-kb

name: vv-kb description: Query the VV knowledge base for tagged observations relevant to the current task. Use when the current task involves VisualVault platform behavior — forms, dashboards, scripting, web services, scheduled processes, admin sections, API quirks, or any VV-specific question. allowed-tools: Bash(node:), Bash(npm:), Read

vv-kb — VisualVault Knowledge Base

The harness ships with a tagged, queryable KB of platform observations under kb/. Each entry carries provenance metadata (customer, environment, vv_version, area, confidence, verification history). Treat the KB as a first reference when working on any non-trivial VV task: it captures hard-won knowledge from prior investigations that would otherwise have to be re-derived.

When to use

Trigger this skill on any task that touches VisualVault platform behavior. Examples:

• Building or debugging a form, dashboard, web service, scheduled process, or workflow.
• Investigating an unexpected behavior (date shift, validation failure, rendering quirk, performance issue).
• Writing a script that uses vvClient.* managers.
• Designing a new pattern that may already have prior art in the KB.
• Any "how does VV do X?" question whose answer the KB might already hold.

Do NOT trigger for trivial syntax questions, one-line edits, or tasks that have no VV-platform component.

How to query

The query CLI is npm run kb:query. All filters AND-compose.

# By component (most common)
npm run kb:query -- --component forms
npm run kb:query -- --component webservices --area api-behavior

# By scope (current customer / environment / version)
npm run kb:query -- --customer wadnr
npm run kb:query -- --version '>=2.4.3'
npm run kb:query -- --customer emanueljofre --environment vvdemo

# By tag (repeatable, ANDed)
npm run kb:query -- --tag ws-bug-1
npm run kb:query -- --tag oauth --tag token-refresh

# Free-text over title + summary + body
npm run kb:query -- --text "blur event"

# By confidence (find canonical platform-truth, or contested entries that need care)
npm run kb:query -- --confidence canonical
npm run kb:query -- --confidence contested

# Compound query
npm run kb:query -- --component forms --customer wadnr --version '>=2.4.3'

# JSON output (use this when piping into other tooling or extracting fields)
npm run kb:query -- --component forms --json

# Limit, help, no-match exit code
npm run kb:query -- --component forms --limit 5
npm run kb:query -- --help
# Exit 0 = matches found, 1 = no matches, 2 = argument error.

After a query returns paths, use Read to open the matched entries in full. The query summary intentionally returns metadata only; entry bodies are not in the query output.

Query-time policy (READ THIS BEFORE APPLYING ANY RESULT)

Every KB entry is a scoped observation, not a universal fact. Before letting an entry shape your work:

1. Identify the current task scope from .env.json (activeServer + activeCustomer) and any version info available. This is your reference scope.
2. Read the entry's scope block in the frontmatter. Note: first_observed, verifications[], contradictions[], confidence.
3. Compute overlap between current scope and observed scope on each dimension (customer, environment, vv_version).
4. Respect the confidence level:
   • canonical — authoritative. Cite the source listed in the entry.
   • corroborated — likely platform-truth. Safe to apply when at least one scope dimension overlaps with the entry.
   • observed — tentative. Verify before applying outside the original scope. State to the user that this is a single-scope observation when relevant.
   • contested — conflicting observations exist. Do not apply silently. Surface the conflict to the user and propose how to determine which side applies to the current scope (often a config toggle or version difference).
5. Treat low-overlap matches as hypotheses, not facts. If the current scope shares zero dimensions with the entry's scope, the entry is a lead, not an answer. State this explicitly when offering it to the user.
6. When the user confirms or contradicts an entry during the task, capture the outcome. The verification CLI (tools/kb/verify.js, Step 8 of v1) is the formal mechanism; until it ships, note the verification or contradiction in your response so it can be filed later by vv-learn.

When you learn something new

If the task surfaces an observation that isn't in the KB, do not write directly to kb/{component}/. Use the vv-learn skill (extended in v1 Step 5), which writes a provisional, tagged entry to kb/_inbox/. Promotion to canonical kb/ happens through vv-kb-promote (v1 Step 7), which is admin-gated via PR.

For now (pre-v1-Step-5), capture new observations as a clearly-marked note in your response so the user can decide whether to invoke the learn flow.

Schema and taxonomy

Two reference files govern entry structure:

• kb/_schema.md — the frontmatter contract, confidence ladder computation rule, ID format, validation rules.
• kb/_taxonomy.md — controlled vocabularies for component, area, confidence, result, environment. customer is open-ended.

Read these only when writing or proposing entries, not for queries.

Output behavior

The CLI's default human-readable output is for terminal use. When you query during a task, prefer the human format unless you need to extract specific fields:

• Human (default): one block per entry showing id, title, component/area, confidence, first_observed, verification/contradiction counts, tags, path, and summary.
• JSON (--json): structured array, useful when the next step is filtering, counting, or selecting a specific field programmatically.

After a query, read the highest-confidence relevant entries in full via Read. The path is the last line of each block (or path field in JSON).