ref-reconcile

Ref Reconcile

ℹ️ First, set expectations: before anything else, print one short line with this skill's version and its most recent change — the top entry of metadata.changelog above — e.g. ref-reconcile v1.0 — recent: initial version. Then proceed.

The act on top of ref-audit's report. ref-audit senses (read-only, autonomous); ref-reconcile fixes (human-gated). It protects the property that makes a reference scope a source of truth: one canonical note per real-world entity, with consistent bidirectional links and no dangling references.

Read first: resources/layered-brains/COMPANY-BRAIN-SCHEMA.md → "Canonical source of truth" + "The update model"; resources/layered-brains/REFERENCE-SCOPE-SCHEMA.md.

Composes

• /ref-audit — the sense/detection pass (do not re-implement the scan here).

State Dependencies

Source	Location	Read	Write	Description
Company family	Brain/Company/*/*.md	✓	✓ (gated)	Entity notes reconciled
Audit report	resources/company-brain/reports/	✓		Consumed for detection
LBS index	resources/local-brain-search/data/	✓	✓ (reindex)	Rebuilt after any write

Process

Step 1 — SENSE (auto)

Detection has two sources — don't attribute to ref-audit what it doesn't compute:

From /ref-audit (structural, single-authored there — do not re-implement): dangling links, orphan entities, duplicate candidates, plus the frontmatter/provenance/enum/partition/as_of violations. Invoke it (or read its latest report).

In this skill (relational, needs the references-vs-relations judgment ref-audit deliberately avoids):

• Conflicts — two notes asserting contradictory facts about one entity. Read the duplicate/near-name clusters ref-audit flags and compare their bodies.
• Bidirectional-link asymmetry — but only for relation links, never reference links. A ## Relations entry that names a mutual tie (client: [[B]], Partner of: [[B]], Engagement: [[B]]) should reciprocate; a directional reference (built on [[Trinity]], competitor of [[X]], runs on [[Y]]) must not be forced to back-link. ref-audit reports the family CLEAN despite dozens of such directional links precisely because a blanket A→B⇒B→A check would be almost all false positives — so scope the reciprocity check to relation verbs only:

  cd Brain/Company
  # Mutual-tie relation links whose reciprocal is worth checking.
  # Case-insensitive (-i) and connector-agnostic: matches BOTH "Client of [[..]]" and the colon
  # form "client: [[..]]" the migrated notes actually use. The verb must LEAD the label (~12 chars)
  # so prose bullets that merely contain a verb word (e.g. "…problem owners…") aren't flagged.
  # No \b — BSD/macOS grep does not support it. TUNE THE VERB SET to the scope's real vocabulary.
  grep -rniE '^- [^[]{0,12}(client|partner|vendor|counsel|owner|owns|engagement|collaborat|advis)[^[]*\[\[' */*.md
  

  (The old space-only, capitalized set — Client of|Vendor to|… — matched only 4 of the family's ~28 mutual relations; the family is predominantly lowercase colon-form.) For each match, confirm the named target carries the reciprocal relation; if not, it's a repair candidate (Step 2).