# Resolving conflicting Knowledge, end to end

A contradiction parks the newer source in review and leaves the incumbent answering. Clearing it means reading both recorded claims, deciding whether they are genuinely incompatible, and changing one of the documents — activation is refused while the conflict stands, so there is no route that acknowledges the problem without fixing it.

- **Status:** Available
- **Audience:** both
- **In the app:** #/knowledge-sources-advanced
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/resolve-conflict/

## The stages

1. Trigger — a source with fact, instruction or playbook authority is added, re-indexed, or promoted to one of those levels.
2. User event — a person supplies the document or changes the level on one already stored.
3. Authentication and workspace resolution — the comparison happens inside one workspace; approved material from anywhere else is not visible to it.
4. Ingest — the extracted text of the new side is prepared, up to the first 16,000 characters.
5. Canonical record — the existing side is assembled from what the workspace has already approved: enabled typed entries in authority-carrying categories, and active sources marked `verified_fact` or `owner_instruction`.
6. Reasoning — a contradiction detector reads both sides as quoted, untrusted data and returns only direct factual contradictions and materially incompatible instructions.
7. Knowledge, memory and rules — up to twenty findings are stored on the source, each with the new claim, the existing claim, a severity and a reason.
8. Autonomy and approval — the source moves to `needs_review` and answers nothing. Activation is refused while a conflict stands; unlike a scanner warning, it cannot be approved away.
9. Action — a person edits, qualifies or retires one of the two documents, then re-indexes the source.
10. Result — the check runs again on the new text. With nothing found, the source becomes `active` and joins retrieval; the incumbent has been answering throughout.
11. Relationship and memory — nothing is written to memory. The reasoning belongs in the review note on the source, where the next person will look.
12. Audit and usage — the detection, every status change, the review with its reviewer and note, and any authority reassessment are all logged; the check itself is metered against the workspace's AI budget.

## Reading the finding before acting on it

| Severity | Typical situation | Usual action |
|---|---|---|
| `high` | Two statements that cannot both be true of the same current policy — a warranty of two years and one of three | Decide which is current; retire or correct the other |
| `medium` | Instructions that pull in different directions, or a scan that could not run | Read both; often a qualifying clause resolves it |
| `low` | A brush rather than a collision — related claims stated at different levels of detail | Frequently a false positive; confirm and clear by rewording |

Roughly half of what is flagged turns out to be two true statements about different cases: a standard lead time beside an expedited one, a list price beside a contracted rate. The fix there is not to choose a winner but to make the distinction explicit in the text of one of them, because a distinction the documents do not state is one an answer cannot make either.

## The four resolutions, and when each fits

1. **Qualify.** Add the condition that separates the two claims — a region, a product line, a customer tier, a date range.
   - Result: Re-index. Both documents survive, and answers can now pick the right one because the words that distinguish them are present.
2. **Correct.** One document is simply wrong or out of date; edit it.
   - Result: Re-index whichever side you changed. If it was a typed entry, the edit takes effect at once.
3. **Retire.** The old document is superseded in full — disable the entry, or delete the source.
   - Result: The claim it made disappears with it, and the conflict clears on the next check.
4. **Demote.** The new document is genuinely useful background but was never meant to carry fact authority; set it to `reference`.
   - Result: The contradiction check does not run at that level, and the material is available as context without being able to prove anything. This is the honest answer for a supplier brochure or a draft.

> **Careful** Demoting is legitimate for material that should never have been factual, and a way of hiding a real disagreement if it is used on a document that genuinely states current policy. The reason belongs in the review note either way.

## What deliberately has no button

- There is no *accept both* — two contradictory statements retrieved together produce an answer that is confidently wrong in one direction or the other.
- There is no *prefer the newest* — the newer file is very often a draft, a supplier's version, or an export of something the business had already amended.
- There is no *let the model decide at answer time* — that would move a decision about what the business promises into the least accountable place available.
- There is no expiry that clears a conflict by waiting. A parked source stays parked, which is why the review queue is worth reading rather than accumulating.

The cost of these absences is a small amount of human attention per conflict. The thing they buy is that every claim Connect makes traces to a document somebody chose over another document, on a date, with a reason recorded.

## Questions

### The two claims are about different products. Is that a bug?

It is the checker being conservative, and it is cheap to clear: name the product in the text of one of them and re-index. That wording also improves retrieval, because a question about one product will now match the passage about that product rather than both.

### Can I activate the source and resolve the conflict afterwards?

No. Activation is refused while a conflict stands, and the refusal says so explicitly. The order is deliberate — a source that answers first and is corrected later has already sent the wrong answer to somebody.

### What if the conflicting claim is in a typed entry rather than a document?

Same resolutions, easier execution. A typed entry can be edited or disabled in seconds, and disabling is the reversible option when you are not yet certain which of the two is current.

## Related

- [When two sources disagree](https://connectbyjbrh.com/docs/knowledge/source-conflict/)
- [Who decides what is true](https://connectbyjbrh.com/docs/knowledge/owner-authority/)
- [The facts editor](https://connectbyjbrh.com/docs/knowledge/facts/)
- [Knowledge sources](https://connectbyjbrh.com/docs/knowledge/sources/)
- [An answer quoted the wrong thing](https://connectbyjbrh.com/docs/troubleshooting/wrong-answer-from-knowledge/)

## What this page is based on

- `backend/app/knowledge_bank.py` — contradiction detection, review rules and activation refusal
- `backend/app/knowledge.py` — the approved material used as the existing side
- Connect capability registry (docs-source/facts.py)