synaptiai Gap and Contradiction Register
Owns what the package does not know, and where its sources disagree. The evidence ledger asserts; this register refuses to.
Iron Law
NEVER RESOLVE A CONTRADICTION BY CHOOSING. Record both sides, name the decision impact, escalate to the owner.
Picking the more convenient version is the single most damaging thing a documentation run can do, because the result is indistinguishable from a verified fact and carries the same authority.
Two registers
| Register | ID | Records |
|---|---|---|
| Assumptions and open questions | AQ-#### |
Something required is not established: a silent source, an inaccessible system, an unstated owner, an assumption the package rests on |
| Contradictions | CT-#### |
Two or more sources disagree about the same claim |
Both live in one file because they answer the same reader question — "what is not settled here?" — and splitting them buries half the answer.
Column schemas and ID grammar: references/register-schemas.md.
Gap classification
Classify on decision impact, not on effort to resolve.
| Class | Definition | Effect on the run |
|---|---|---|
| Blocking | Documentation would materially mislead a reader without resolution | Drafting of the affected document stops. Everything else continues |
| Material, non-blocking | The package can proceed with a visible qualification in the affected document | Draft with the qualification inline; the row stays open |
| Minor | Useful refinement, not decision-changing | Record it, draft normally |
Do not stall the entire package for a non-blocking unknown. A package delivered with twelve honest open questions is more useful than a package delayed indefinitely for one of them.
Before escalating a blocking gap
In this order. Escalation is the last step, not the first.
- Search again by a different route. A different search term, a different directory, git history, a schema, a test fixture, a configuration default. Most gaps are findable, and the first search was one route.
- Run a safe check the action ceiling permits. An executed command answers what a document may only assert.
- Ask a concise, evidence-seeking question — only if a person genuinely must resolve it, and only when
allowedActions.contactHumansis true. Ask for the specific artifact, not for an explanation: "Is there an approved data-retention record for the analytics store?" beats "Can you explain how retention works?" - Otherwise mark the affected claims and documents unresolved and continue.
Recording a contradiction
Every CT-#### row carries:
- Both claims verbatim, each with its evidence ID, authority level, and observation date
- The likely cause — most contradictions are staleness, environment difference, or scope difference, not error
- The decision impact: which reader, making which decision, would be misled by picking the wrong side
- Current resolution or
unresolved, with an owner and the next verification action
The likely-cause analysis matters because it usually dissolves the conflict. "The IaC says three replicas, the dashboard shows two" is often not a disagreement at all — it is a claim about the file and a claim about the running system, which are different claims and want different rows.
When authority levels differ, the higher level is preferred, not correct. Record both, prefer one, and say which and why. Higher authority is not the same as more current.
Resolution
A contradiction is resolved when new evidence settles it — not when someone decides. Record the settling evidence ID and the reasoning. Both original rows stay in the ledger; the superseded one gains a Notes entry pointing at its successor.
An owner accepting one side without new evidence is not resolution; it is an accepted risk, recorded as such, with the accepting authority named. That distinction is what a diligence reader is actually looking for.
Owner-decision items
Some rows cannot be closed by any amount of inspection: a business decision, a legal interpretation, a disclosure approval, a risk acceptance. Mark these needs-owner. They are not failures of the run, and they must not be quietly dropped at the end.
needs-owner rows block the release gate. That is deliberate — an unmade decision is a real reason a package is not ready.
Output Format
Two tables in 00-control/assumptions-questions-and-contradictions.md, plus the derived views below.
## Assumptions and Open Questions
| ID | Question or assumption | Why it matters | Working position | Evidence needed | Owner | Class | Affected documents | Status |
|---|---|---|---|---|---|---|---|---|
| AQ-0001 | {question} | {decision it changes} | {what the package currently assumes} | {the smallest artifact that would settle it} | {role or `unassigned`} | blocking / material / minor | {paths} | open / resolved / needs-owner |
## Contradictions
| ID | Claim A (evidence, authority, date) | Claim B (evidence, authority, date) | Likely cause | Decision impact | Resolution | Owner | Next action |
|---|---|---|---|---|---|---|---|
| CT-0001 | {verbatim} [EV-0042, L2, 2026-07-20] | {verbatim} [EV-0043, L3, 2026-07-24] | {staleness / environment / scope / error} | {who is misled, deciding what} | unresolved | {role} | {specific check} |
Also emit, ordered by decision impact rather than by ID:
### Blocking decisions
### Recommended evidence requests
| Request | Settles | Decision impact | Owner |
The evidence-request list is the highest-value output of this skill. It converts "we do not know" into "here is the one artifact that would tell us", which is the difference between a complaint and a deliverable.
Rationalization Prevention
| Excuse | Response |
|---|---|
| "The code is authoritative, the doc is just stale" | Then say so in a CT- row with that as the likely cause. Do not delete one side. |
| "This contradiction is too minor to record" | Then it is a minor-class row and costs one line. Judging it minor without recording it is how it stops being minor unnoticed. |
| "I will ask the user about all twelve unknowns" | Ask about the blocking ones. The rest go in the register — that is what it is for. |
| "Nobody owns this component, so I will list the last committer" | The last committer is not an owner. unassigned is true; a name is a fabrication with consequences during an incident. |
| "The team will know which is right" | Then record both and ask them. Guessing on their behalf removes their chance to answer. |
| "It resolved itself once I read more code" | Then new evidence settled it — record the settling evidence ID. Silent disappearance is not resolution. |
| "This gap is unresolvable so there is no point recording it" | An unresolvable gap is exactly what a diligence reader most needs to see. |
Integration
Invoked in Phase 3 of /dossier:baseline, throughout /dossier:refresh, and by /dossier:reconcile when a finding cannot be repaired by the agent. finding-reconciliation routes cross-pass disagreements here as CT- rows. bin/dossier-gate.sh reads the needs-owner and blocking counts as gate inputs.
References: references/register-schemas.md, references/source-authority-and-claim-states.md, references/finding-schema.md.