Layer 3: AI Deep Review | Visdom Code Review

Full analysis. Triggered only for MEDIUM+ risk PRs. Expensive but high-value. Each review category runs as an independent Review Lens, a separate prompt with its own focus area and output schema. Lenses run in parallel.

Input

Everything from previous layers, plus:

Full files (not just diff): AI sees the entire module
Related files: files imported by changed files (from dependency graph)
Org conventions: standards.sources documents and instructions from .visdom.yaml, plus org rules in .visdom/rules/
Historical context: how this module evolved (from repository knowledge layer)

Review Lenses (Visdom Standard)

Lens	Focus	When active
Security	Injection, auth bypass, data exposure, OWASP Top 10	Always on MEDIUM+
Correctness	Logic errors, broken contracts, hallucinated APIs, edge cases the diff does not handle	Always on MEDIUM+
Test Quality	New paths have tests, assertion quality, edge cases, circular test detection	Always on MEDIUM+
Performance	N+1 queries, blocking I/O, quadratic algorithms, unbounded caches	Default on, `min_severity: medium`
Maintainability	Duplication, God objects, structural decay	Opt-in via `.visdom.yaml` (disabled by default)

These five lenses are the complete set. AI-typical failure modes (hallucinated APIs, over-engineering, unnecessary abstractions) are covered by the correctness and security lenses plus Layer 1 rules, and team conventions are enforced through org rules and instructions — neither has a separate lens.

Circular Test Detection

The Test Quality lens includes explicit detection of circular tests, tests derived from implementation rather than specification:

Examine new/modified tests. For each test, determine:
1. Does this test verify behavior described in a spec/issue/PR description?
   OR does it mirror the implementation logic?
2. Does this test cover negative paths, edge cases, invalid inputs?
   OR only the happy path that the implementation handles?
3. Would this test FAIL if the implementation had a subtle bug
   (off-by-one, missing null check, wrong status code)?
   OR would it pass because it tests the same logic?

Flag as CIRCULAR if the test would pass regardless of correctness.

✅ Why This Matters

Circular tests are the core failure mode of AI-generated test suites. They verify what code does, not what it should do. A circular test suite gives 100% coverage and 0% confidence.

Extending the review

Clients add domain-specific checks via org rules (.visdom/rules/*.rules.yaml) and steer the lenses with instructions and standards.sources in .visdom.yaml — not by defining new lenses:

standards:
  sources: ["docs/standards/*.md"]     # your existing docs, injected into deep review
rules:
  - .visdom/rules/org.rules.yaml       # org-defined checks (type: pattern or type: llm)
instructions: "When a finding violates a document under docs/standards/, cite the document path."

Output per Lens

Each lens produces structured findings in a consistent JSON schema:

{
  "lens": "security",
  "findings": [
    {
      "severity": "HIGH",
      "file": "src/api/auth.ts",
      "line": 42,
      "category": "SQL Injection",
      "description": "User input interpolated directly into query",
      "suggestion": "Use parameterized query: db.query('SELECT ...', [userId])",
      "confidence": 0.95
    }
  ]
}

Findings from all lenses are aggregated by the Reporter into a single structured PR comment with inline annotations.