← anatomy · cross-cutting rules · contradictions
04 · CROSS-CUTTING RULES

Contradictions.

CONTRADICTION: block under ## Notes

The most important rule in the wiki. When a new source disagrees with an existing page, never silently overwrite. Log both versions, both sources, both stakeholders — and surface it.

2026-03-14 postmortem SRE team "connection pool exhaustion" 2026-04-02 postmortem payments team "slow downstream call" ## Notes CONTRADICTION: both versions logged both sources cited resolution: open

Both versions live on the page. A human picks the winner — not the wiki.

THE RULE
When a new source contradicts an existing page, never silently overwrite. Add a CONTRADICTION: block under Notes capturing both versions, both sources, both dates, and both stakeholder positions.
— CLAUDE.md · the contract that keeps the wiki honest

A CONTRADICTION block, in full

wiki/root-causes/connection-pool-exhaustion.mdspecimen · Notes section
## Notes

CONTRADICTION: Root cause attribution differs between two incidents
with identical symptoms.

- 2026-03-14 postmortem (raw/postmortems/2026-03-14-checkout.md, SRE
  team): blamed connection pool exhaustion in payments-db. Fix:
  raised pool size from 50 to 200.
- 2026-04-02 postmortem (raw/postmortems/2026-04-02-checkout.md,
  payments team): same symptoms with the larger pool. Blamed slow
  downstream call to fraud-scoring; argued the pool exhaustion was a
  downstream effect, not a root cause.

Both incidents are linked. The unifying explanation ("downstream slow
call holds upstream resources") is open. Resolution: needs cross-team
review.

What a contradiction must capture

  1. Both versions — stated plainly, without preferring one.
  2. Both sources — the raw/ paths so a reader can verify.
  3. Both dates — when each version was written.
  4. Both stakeholders — which team or person held each view.
  5. Resolution status — open, under review, or who owns the next step.

How contradictions ripple through the wiki

  1. The CONTRADICTION: block lives on the affected page under ## Notes.
  2. The day's log.md entry records the contradiction in its contradictions surfaced field.
  3. The next index.md refresh adds the page to Open contradictions with a one-line summary.
  4. tools/lint.py flags CONTRADICTION: blocks as warnings, not errors — so they stay visible until a human resolves them.
  5. When resolved, the block is replaced by a "Resolved on YYYY-MM-DD" note explaining which version was accepted and why.

Rules

  1. Never silently overwrite. If a new source disagrees, log it; don't decide for the humans.
  2. Use the literal token CONTRADICTION: at the start of the block — that's what the tools and the index look for.
  3. Preserve the original page content — the contradiction is added alongside it, not instead of it.
  4. If you got a previous ingest wrong, log a corrective entry in log.md rather than rewriting history on the page.
  5. The wiki surfaces disagreements; humans resolve them.