Troubleshooting Reconciliation

Common issues encountered during reconciliation and how to resolve them.

“Reconciliation flags too many false positives”

Symptom: Reconciliation reports drift on files that have not meaningfully changed, or flags changes that are intentional.

Causes and fixes:

• Overly broad artifact globs. A glob like src/**/*.rs may include utility files, generated code, or test helpers that change frequently without affecting the spec’s intent. Narrow the globs to match only the files the spec actually governs.

• Missing exclude patterns. Generated files, lock files, and build artifacts should be excluded at the system spec level. Add patterns to the exclude array in your system spec.

• Spec covers too much. If a single spec governs 50+ files, it will flag drift on every PR that touches any of them. Split large specs into focused subsystems.

“Reconciliation misses obvious drift”

Symptom: Code has clearly diverged from the spec, but reconciliation reports no findings.

Causes and fixes:

• Stale cache. The BLAKE3 cache may show files as unchanged if they were marked reconciled after a previous session. Try running with bypass_cache: true on the MCP get_spec_diff tool, or clear the cache:

  notarai cache clear
  

• Behaviors do not cover the changed area. Reconciliation evaluates drift against the behaviors listed in the spec. If the changed code is not described by any behavior, the LLM has nothing to compare against. Add behaviors for the critical paths you want monitored.

• Wrong base branch. The reconciliation prompt compares against a base branch (default: main). If you are working on a long-lived feature branch, the diff may not include the changes you expect. Specify the correct base:

  notarai export-context --all --base-branch develop
  

“Context window is too large”

Symptom: The reconciliation prompt exceeds the LLM’s context window, or the LLM produces shallow analysis because the context is too dense.

Causes and fixes:

• Use exclude_patterns in get_spec_diff. The MCP tool accepts an exclude_patterns array of glob strings that suppress noisy files from the diff output. Common candidates: lock files, snapshot files, auto-generated code.

• Split large specs into subsystems. A spec governing 30+ files produces a large diff. Break it into focused subsystems with $ref links. Reconciliation processes each spec independently, keeping context proportional to each subsystem’s changes.

• Let the cache work. Files that have not changed since the last reconciliation are automatically excluded from the diff. Run notarai cache status to verify the cache is populated. If it is empty, the first reconciliation will include everything; subsequent runs will be incremental.

“Spec and code intentionally diverged”

Symptom: You know the code has changed in ways that do not match the spec, and you want to acknowledge this without updating the spec immediately.

Fix: Add a decisions entry to the spec explaining the divergence:

decisions:
  - date: '2026-04-10'
    choice: 'Temporarily diverge from retry spec during migration'
    rationale: >
      The old retry logic is being replaced incrementally. The spec
      describes the target state. Code will converge over the next
      two sprints.

Then mark the affected files as reconciled so they do not trigger repeated warnings:

# Via MCP (in a Claude Code session):
# The mark_reconciled tool updates the cache for specified files.

# Via CLI:
notarai state snapshot

“notarai check reports errors but reconciliation says everything is fine”

Symptom: notarai check finds issues (orphaned globs, coverage gaps) but the LLM-based reconciliation does not mention them.

Explanation: notarai check runs deterministic, structural checks. LLM-based reconciliation evaluates semantic alignment. They are complementary:

• check catches: orphaned globs, coverage gaps, overlapping specs, circular refs, stale cache entries
• reconciliation catches: behavioral drift, outdated constraints, misaligned documentation

Run both. Use notarai check in CI for fast, deterministic feedback. Use /notarai-reconcile during development for deeper semantic analysis.

“Bootstrap interview produces a spec that does not validate”

Symptom: The spec generated by /notarai-bootstrap fails notarai validate.

Fix: This usually means the LLM produced a field or value not in the JSON Schema. Common issues:

• Unknown artifact category. The schema allows code, docs, tests, configs, and several others. If the LLM invented a category like scripts, rename it to a supported one or use a custom key.

• Missing required fields. Every spec needs schema_version, intent, and artifacts. If the LLM omitted one, add it.

• Wrong schema_version. The LLM may have used an older version string. Run notarai schema-bump to update all specs to the current version.