Source Of Truth Reconciler

---
name: source-of-truth-reconciler
description: Resolve conflicts between current user instructions, repo docs, code, tests, PR history, and older chat or memory context before acting on any of them. Use when two sources disagree (a doc says X, the code does Y), when instructions reference repo state that no longer exists, when planning docs overlap or contradict, or when remembered context conflicts with what the repo actually contains. Produces a precedence-ordered reconciliation with cited evidence (file:line) and surfaces every assumption explicitly — never silently picks a side and never silently obeys a stale instruction. Do NOT use for the cadenced sweep of chat-only decisions into repo docs (chat-backlog-reconciliation).
---

# Source-of-Truth Reconciler

**Reading key:** A pull request (PR) proposes a repository change; an
application programming interface (API) is how programs call a service. A
*canonical* doc is one the repository officially designates as the
authority on its topic. A *normative* decision settles what should be true
(intent or policy), as opposed to describing what currently is.

## Purpose

Turn "the sources disagree" into a recorded, evidence-backed decision. This
skill enumerates the conflicting claims, classifies each conflict, applies a
declared precedence order, and outputs a reconciliation report that cites its
evidence — so downstream work builds on one resolved truth instead of a quiet
guess. It also carries the no-silent-assumptions rule: every assumption made
while reconciling is stated with its risk.

## Use When

- Use when: a doc contradicts the code or tests.
- Use when: the user's instruction references state that no longer exists
  (deleted branch, moved file, superseded plan).
- Use when: two planning docs cover the same ground with different answers.
- Use when: recalled memory or prior-chat context conflicts with current repo state.
- Do NOT use when: nothing conflicts — plain reading needs no reconciliation.
- Do NOT use when: the question is whether a risky action may proceed — that is
  `human-approval-boundary`.
- Do NOT use when: starting a task and loading context — that is
  `agent-startup-context-gate` (it may HAND OFF here when it finds a conflict).
- Do NOT use when: sweeping chat-only decisions into repo docs on a cadence
  — that is `chat-backlog-reconciliation`; this skill resolves a live
  conflict between sources.

## Inputs to Inspect

1. The conflicting claims themselves — quote each verbatim with its anchor
   (file:line, PR number, message).
2. Source metadata: dates, canonical/historical markers, reconciliation records.
3. Actual repo state: the code, tests, and migrations as they are now.
4. Merged PR and commit history, for claims about what happened.
5. Any repo-designated precedence policy — it overrides the default order below.

## Workflow

1. **Enumerate claims verbatim**, each with an evidence anchor.
2. **Tag each source:** type, date, and status — canonical | current |
   historical | generated | memory.
3. **Classify each conflict:** an IS-question (what does the system actually
   do?) or a SHOULD-question (what is intended/required?).
4. **Apply precedence** (default; a repo policy overrides it):
   1. Explicit current-session user instruction — unless it rests on stale
      facts (surface and confirm first) or crosses a safety boundary (route to
      `human-approval-boundary` when the conflict requires a normative or
      authorization decision).
   2. For IS-questions: actual repo state — code, tests, migrations.
   3. Docs marked canonical / current reconciliation records — for
      SHOULD-questions these outrank code (intent-vs-implementation drift is a
      finding to report, not a tie).
   4. Merged PR and commit history.
   5. Historical or superseded docs.
   6. Prior chat memory / recalled context.
5. **Record a verdict per conflict:** winner, precedence rule applied, evidence.
   If no rule yields a winner and only an owner can decide which source is
   authoritative (two owner-controlled docs disagree, or live state contradicts
   an approved record and neither is clearly authoritative), teach the choice
   before asking. Define terms plainly: the *authoritative source* is the one
   later work must follow; *UNRESOLVED* means both claims stay recorded and
   dependent work waits. Compare adopting source A, adopting source B, and
   holding as UNRESOLVED pending the owner: why each is viable, its pros and
   cons, and its correction effort (which sources, records, or behavior would
   need follow-up change) or explicit unknowns. Recommend one when the
   evidence supports it — holding UNRESOLVED is the recommendation when it
   does not — explain why, name the evidence that would change it, then ask
   exactly one owner question. Never silently pick a winner; recency and
   confidence are not authority. An answer adopting A or B settles which
   source governs; choosing UNRESOLVED keeps dependent work waiting. No
   answer itself authorizes editing sources, changing live systems, or other
   follow-up work. Conflicts touching security, data handling, tenant
   isolation, or destructive behavior still follow Stop Conditions.
6. **Surface every assumption** made along the way, each with risk-if-wrong.
7. **Propose corrections** to the losing stale sources as follow-up work — do
   not silently edit them as a side effect of reconciling.

## Output Format

```
RECONCILIATION REPORT
Conflicts:
  C1: <claim A (source:line)> vs <claim B (source:line)>
      Type: IS | SHOULD
      Verdict: <winner> — precedence rule <n>, because <reason>
Assumptions surfaced: <each with risk-if-wrong>
Stale sources to fix: <file → proposed correction (follow-up, not done here)>
Blocked: <conflicts with no winner — questions for the human>
Owner choice (next blocking conflict only; others stay under Blocked for
  later turns): <plain terms; adopt A / adopt B / hold
  UNRESOLVED — why viable, pros/cons, correction effort or unknowns;
  recommendation, why, and what evidence would change it; ONE owner question;
  follow-up changes separately authorized>
```

## Validation Checklist

- [ ] Every claim quoted with a file:line / PR / message anchor.
- [ ] Every verdict names the precedence rule it applied.
- [ ] IS vs SHOULD recorded per conflict.
- [ ] No stale source silently edited; fixes proposed as follow-ups.
- [ ] Every assumption listed with its risk-if-wrong.
- [ ] Each owner-decided conflict explains terms, each viable resolution's
      reason, pros/cons, and effort or unknowns, and a reasoned recommendation
      before exactly one owner question; no winner is picked by recency or
      confidence, and the answer authorizes no follow-up edit by itself.
- [ ] Unresolved normative, authorization, or proposed posture changes in
      security/data handling route to `human-approval-boundary`; read-only
      IS-questions report verified current behavior without changing it.

## Gotchas

- Recently modified is not canonical — a stale doc can carry a fresh timestamp
  from an unrelated touch-up.
- The user's instruction can itself be stale (built on a view of the repo that
  has moved on). Surfacing that and confirming beats both silently obeying and
  silently overriding.
- Docs describing DESIRED state read like descriptions of CURRENT state;
  misclassifying SHOULD as IS inverts the verdict.
- Two docs may both claim to be canonical — that is a conflict to escalate, not
  one to resolve by picking the newer file.
- Generated artifacts (lockfiles, build output, generated API docs) mirror
  their inputs; citing them as an independent source double-counts one claim.

## Stop Conditions

- An unresolved SHOULD-question or proposed change affects security, data
  handling, tenant isolation, or destructive behavior → stop and route the
  decision to `human-approval-boundary`. A read-only IS-question can report
  verified current behavior and its evidence without authorizing a change.
- Two sources of equal current standing disagree and no repo precedence policy
  exists → stop and ask.
- Resolution would require rewriting docs or history beyond the current task's
  scope → propose it, don't do it.

## Supporting Files

- [references/conflict-resolution-examples.md](references/conflict-resolution-examples.md) —
  worked examples: doc-vs-code, stale-branch instruction, dueling canonical docs.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination against `agent-startup-context-gate`,
  `human-approval-boundary`, and `rls-policy-auditor`.