Verification

Detect drift between your documentation and code. Verification mode compares what your docs claim against what the code actually does, classifies discrepancies by severity, and produces a fix plan.

When to use

Run /uc:doc-code-verification-mode after major changes, before releases, or as a periodic audit. You can scope it to a specific directory, topic, or run it across the entire project.

Three dimensions of verification

Verification checks accuracy, structure, and redundancy — three different problems with different fixes.

Code-documentation accuracy

Pairs documentation sections with the code they describe, then spawns Checker agents to compare claims against reality. Each discrepancy gets a severity level and file:line references.

Critical — phantom docs describing code that doesn't exist
Major — undocumented code, significant behavioral drift
Minor — naming differences, formatting issues

Documentation structure adherence

Verifies your docs follow the canonical structure: correct directories, expected sections present, cross-references between related docs (with anchors that resolve to real headings), no content duplication across document types.

Critical — document in wrong directory (routing violation)
Major — missing key sections, missing cross-references, broken cross-reference anchors, duplicated content
Minor — formatting deviations

Documentation redundancy

Catches the same drift-prone content — schemas, config values, counts, versions, definitions, procedures — copied across multiple documents (distinct from wrong-doc-type placement above). Each fact should have one canonical home that everything else links to; a brief orienting summary that links to the source is fine, wholesale copies are not.

Critical — a spec, value, count, version, or contract shape copied verbatim across docs
Major — substantial overlapping procedures or definitions to consolidate
Minor — small repeated substantive phrasing

Fix classification

For each discrepancy, verification classifies the fix type:

Update docs — the code is correct, docs need to catch up
Update code — the docs are correct, code has drifted
Consolidate — duplicated content merged into one canonical home, copies replaced with cross-links
Needs decision — unclear which is right, flagged for you to decide

How the verification matrix works

The process builds a verification matrix pairing each documentation section with its corresponding code:

Doc Surveyor and Code Surveyor agents scan the project in parallel
The AI builds a matrix mapping doc sections to code components
Checker agents are spawned for each pair — each returns discrepancies with severity and evidence
Results are deduplicated and synthesized into a single report

The AI then walks through findings with you. For each discrepancy, you decide: update docs, update code, fix structure, consolidate, or skip. Only the fixes you approve go into the plan.

Scoped verification

You can focus verification on specific areas:

/uc:doc-code-verification-mode src/auth/ — verify a specific directory
/uc:doc-code-verification-mode authentication — verify a specific topic
/uc:doc-code-verification-mode — verify the entire project

For large codebases, scoped verification is recommended — full-project scans can be resource-intensive.

What it produces

A discrepancy report followed by a fix plan in documentation/plans/ containing only the fixes you approved. Additionally, features described in documentation but not implemented at all are listed separately for your prioritization — you're asked what to do with each one — add to backlog, handle now, or ignore.

Closing the loop

Verification is the final piece of the standards enforcement loop. You define standards, the Code Reviewer enforces them during execution, and Verification mode audits that reality still matches documentation over time.