Configuration | Visdom Code Review

Configuration is split across two layers: tool-shipped defaults and a per-repository .visdom.yaml override file. Both are validated against zod schemas in demo/src/core/config/schema.ts.

How configuration resolves

At startup the engine deep-merges demo/config/defaults.yaml with the repository's .visdom.yaml. The merge rules are:

Scalars — repository value wins.
Lists (rules, ignore.paths, standards.sources) — concatenated; tool defaults are preserved unless explicitly disabled.
Inherited rules — disable any loaded rule by id — tool defaults or your own — via disable_rules.
Lens overrides — keyed by lens name; only the keys present in .visdom.yaml are merged.

💡 Error philosophy

An invalid .visdom.yaml produces a readable warning and falls back to tool defaults — the review still runs. An unparseable rule file is skipped with a warning naming the file. An invalid individual rule inside a valid file is skipped with a warning naming both the file and the rule id. A config error degrades the review; it never kills it.

.visdom.yaml

Place this file at the repository root. All fields are optional; omit any section to keep the tool default.

enabled: true                          # opt-in per repository
ignore:
  paths: ["**/generated/**", "*.lock"]
lenses:                                # five lenses; per-lens overrides
  security:        { enabled: true,  min_severity: low }
  correctness:     { enabled: true,  min_severity: low }
  test-quality:    { enabled: true,  min_severity: low }
  performance:     { enabled: true,  min_severity: medium }
  maintainability: { enabled: true,  min_severity: medium }   # tool defaults: disabled, min_severity high
standards:
  sources: ["docs/standards/*.md", "CLAUDE.md"]   # your existing docs, injected into deep review
rules:
  - .visdom/rules/org.rules.yaml       # repo-local rule files (merged with tool defaults)
disable_rules: [correctness/optional-get-unchecked]
instructions: "When a finding violates a document under docs/standards/, cite the document path."
limits:
  max_findings: 5                      # higher than built-in lens caps (2–3); binding only for lenses that exceed it
  confidence_buckets: { high: 0.8, medium: 0.5 }

Field reference

Field	Effect
`enabled`	Set to `false` to opt this repository out of review entirely.
`ignore.paths`	Glob list. Matching files are excluded from all lens analysis. Concatenated with tool defaults.
`lenses.<name>.enabled`	Enable or disable a lens for this repository. Tool defaults: security, correctness, test-quality, performance enabled; maintainability disabled.
`lenses.<name>.min_severity`	Findings below this severity are not reported. Values: `critical`, `high`, `medium`, `low`.
`standards.sources`	Glob list of existing repo docs injected into deep-review prompts. Hard 800-line cap; truncation is reported in the review output. Concatenated with tool defaults.
`rules`	Paths to repo-local rule files (relative to repo root). Concatenated with tool-default rule files.
`disable_rules`	Disable any loaded rule by id — tool defaults or your own.
`instructions`	Free-text appended to every lens prompt. Use to add org-wide conventions the model should reference.
`limits.max_findings`	Ceiling on findings per lens. Each lens has its own default cap (2–3); this value only lowers them further. Default: 5 (non-binding for the built-in lenses).
`limits.confidence_buckets`	Thresholds that map a raw confidence score to high / medium / low labels. Default: high ≥ 0.8, medium ≥ 0.5. (rendering details: see Confidence buckets below)

The unified rule schema

Both tool-default rules and repo-local rules use the same file envelope, discriminated by type: pattern | llm. The examples below are the two rules that ran on a real PR: llama3-java-hat#50.

version: 1
rules:
  - id: llama3/no-stdout-logging
    type: pattern
    severity: medium
    category: maintainability
    languages: [java]
    message: "System.out logging in library code"
    help: "Library code must not write to stdout; tensor loading runs in tight loops and stdout flushes destroy throughput."
    fix_hint: "Use the project Logger; stdout is reserved for the CLI entrypoint."
    pattern: { regex: "System\\.out\\.print" }
  - id: llama3/tensor-ops-document-shape
    type: llm
    severity: high
    category: correctness
    paths: { include: ["**/tensor/**", "**/*Tensor*.java"] }
    instruction: |
      Every public method that creates, reshapes, or maps a tensor must validate (or explicitly document)
      the expected dimensions/shape of its inputs. Silent shape mismatches surface as garbage inference output.
    success_criteria: "Tensor-handling methods in the diff validate dimensions or carry a shape contract comment."
    failure_criteria: "A tensor-handling method accepts arrays/buffers with no dimension validation and no documented shape contract."
    examples:
      bad: 'public FloatTensor mapRow(float[] data) { return new FloatTensor(data); }'
      good: 'public FloatTensor mapRow(float[] data) { if (data.length != dim) throw new IllegalArgumentException(...); return new FloatTensor(data); }'
    message: "Tensor operation lacks shape validation or documented contract"

pattern rules run in the deterministic layer — zero LLM cost, zero variance. The engine matches the regex (or a named builtin) against changed lines.

llm rules become numbered checklist items inside the matching lens prompt, scoped to files that match paths.include. The success_criteria, failure_criteria, and examples.good/examples.bad fields are required practice: they reduce LLM judgment ambiguity by replacing open-ended instructions with concrete pass/fail conditions.

Standards injection

The standards.sources field accepts glob patterns resolved from the repository root. Matching files are read and prepended to deep-review prompts. There is a hard 800-line cap; files that exceed it are truncated and the truncation is reported in the review output.

The intent is to reuse documentation you already maintain — architecture decision records, API style guides, team conventions — without writing new files specifically for the tool.

Confidence buckets

Label	Threshold	Rendered as
high	≥ 0.8	Finding reported directly.
medium	≥ 0.5	Finding reported with lower priority.
low	below medium threshold	"Requires verification" note in review comments.

Both thresholds are configurable via limits.confidence_buckets in .visdom.yaml.

💡 What this replaces

Earlier drafts of this page described a .vcr/vcr-config.yaml layout that predated the implementation. The format documented here is what the engine validates — zod schemas in demo/src/core/config/schema.ts.