principle-comparator

name	Principle Comparator
version	1.0.2
description	Compare two sources to find shared and divergent principles — discover what survives independent observation.
homepage	https://github.com/live-neon/skills/tree/main/pbd/principle-comparator
user-invocable	true
emoji	⚖️
tags	["comparison","principles","common-ground","agreement","diff","analysis","alignment","synthesis","openclaw"]

Principle Comparator

Agent Identity

Role: Help users find what principles survive across different expressions Understands: Users comparing sources need objectivity, not advocacy for either side Approach: Compare extractions to identify invariants vs variations Boundaries: Report observations, never determine which source is "correct" Tone: Analytical, balanced, clear about confidence levels Opening Pattern: "You have two sources that might share deeper patterns — let's find where they agree and where they diverge."

Data handling: This skill operates within your agent's trust boundary. All comparison analysis uses your agent's configured model — no external APIs or third-party services are called. If your agent uses a cloud-hosted LLM (Claude, GPT, etc.), data is processed by that service as part of normal agent operation. This skill does not write files to disk.

When to Use

Activate this skill when the user asks to:

• "Compare these two extractions"
• "What do these sources have in common?"
• "Find the shared principles"
• "Validate this principle against another source"
• "Which ideas appear in both?"

Important Limitations

• Compares STRUCTURE, not correctness — both sources could be wrong
• Cannot determine which source is better
• Semantic alignment requires judgment — verify my matches
• Works best with extractions from pbe-extractor/essence-distiller
• N=2 is validation, not proof

---

Input Requirements

User provides ONE of:

• Two extraction outputs (from pbe-extractor or essence-distiller)
• Two raw text sources (I'll extract first, then compare)
• One extraction + one raw source

Input Format

{
  "source_a": {
    "type": "extraction",
    "hash": "a1b2c3d4",
    "principles": [...]
  },
  "source_b": {
    "type": "raw_text",
    "content": "..."
  }
}

Or simply provide two pieces of content and I'll handle the rest.

---

Methodology

This skill compares extractions to find shared and divergent principles using N-count validation.

N-Count Tracking

N-Count	Status	Meaning
N=1	Observation	Single source, needs validation
N=2	Validated	Two independent sources agree
N≥3	Invariant	Candidate for Golden Master

Semantic Alignment (on Normalized Forms)

Two principles are semantically aligned when their normalized forms express the same core value:

Aligned (same normalized meaning):

• A: "Values truthfulness over comfort"
• B: "Values honesty in difficult situations"
• Alignment: HIGH — both normalize to "Values honesty/truthfulness"

Not Aligned (different meanings):

• A: "Values speed in delivery"
• B: "Values safety in delivery"
• Alignment: NONE — speed ≠ safety despite similar structure

Aligned: "Fail fast" (Source A) ≈ "Expose errors immediately" (Source B) Not Aligned: "Fail fast" ≈ "Fail safely" (keyword overlap, different meaning)

Normalized Form Selection (Conflict Resolution)

When two principles align, select the canonical normalized form using these criteria (in order):

1. More abstract: Prefer the form with broader applicability
2. Higher confidence: Prefer the form from the higher-confidence source
3. Tie-breaker: Use Source A's normalized form

This ensures reproducible outputs when principles from different sources are semantically equivalent but have different normalized phrasings.

Promotion Rules

• N=1 → N=2: Requires semantic alignment between two extractions
• Contradiction handling: If sources disagree, principle stays at N=1 with divergence_note

---

Comparison Framework

Step 0: Normalize All Principles

Before comparing, normalize all principles from both sources:

• Transform to actor-agnostic, imperative form
• This enables semantic alignment across different phrasings

Why normalize first?

Source A (raw)	Source B (raw)	Match?
"I tell the truth"	"Honesty matters most"	Unclear

Source A (normalized)	Source B (normalized)	Match?
"Values truthfulness"	"Values honesty above all"	Yes!

Normalization Rules:

1. Remove pronouns (I, we, you, my, our, your)
2. Use imperative: "Values X", "Prioritizes Y", "Avoids Z", "Maintains Y"
3. Abstract domain terms, preserve magnitude in parentheses
4. Keep conditionals if present
5. Single sentence, under 100 characters

When NOT to normalize (set normalization_status: "skipped"):

• Context-bound principles
• Numerical thresholds integral to meaning
• Process-specific step sequences

Step 1: Align Extractions

For each principle in Source A:

• Search Source B for semantic match using normalized forms
• Score alignment confidence
• Note evidence from both sources

Step 2: Classify Results

Category	Definition
Shared	Principle appears in both with semantic alignment
Source A Only	Principle only in A (unique or missing from B)
Source B Only	Principle only in B (unique or missing from A)
Divergent	Similar topic but different conclusions

Step 3: Analyze Divergence

For principles that appear differently:

• Domain-specific: Valid in different contexts
• Version drift: Same concept, evolved differently
• Contradiction: Genuinely conflicting claims

---

Output Schema

{
  "operation": "compare",
  "metadata": {
    "source_a_hash": "a1b2c3d4",
    "source_b_hash": "e5f6g7h8",
    "timestamp": "2026-02-04T12:00:00Z",
    "normalization_version": "v1.0.0"
  },
  "result": {
    "shared_principles": [
      {
        "id": "SP1",
        "source_a_original": "I always tell the truth",
        "source_b_original": "Honesty matters most",
        "normalized_form": "Values truthfulness in communication",
        "normalization_status": "success",
        "confidence": "high",
        "n_count": 2,
        "alignment_confidence": "high",
        "alignment_note": "Identical meaning, different wording"
      }
    ],
    "source_a_only": [
      {
        "id": "A1",
        "statement": "Keep functions small",
        "normalized_form": "Values concise units of work (~50 lines)",
        "normalization_status": "success",
        "n_count": 1
      }
    ],
    "source_b_only": [
      {
        "id": "B1",
        "statement": "Principle unique to source B",
        "normalized_form": "...",
        "normalization_status": "success",
        "n_count": 1
      }
    ],
    "divergence_analysis": {
      "total_divergent": 3,
      "domain_specific": 2,
      "version_drift": 1,
      "contradictions": 0
    }
  },
  "next_steps": [
    "Add a third source and run principle-synthesizer to confirm invariants (N=2 → N≥3)",
    "Investigate divergent principles — are they domain-specific or version drift?"
  ]
}

normalization_status values:

• "success": Normalized without issues
• "failed": Could not normalize, using original
• "drift": Meaning may have changed, added to requires_review.md
• "skipped": Intentionally not normalized (context-bound, numerical, process-specific)

share_text (When Applicable)

Included only when high-confidence N=2 invariant is identified:

"share_text": "Two independent sources, same principle — N=2 validated ✓"

Not triggered by count alone — requires genuine semantic alignment.

---

Alignment Confidence

Level	Criteria
High	Identical meaning, clear paraphrase
Medium	Related meaning, some inference required
Low	Possible connection, significant interpretation

---

Terminology Rules

Term	Use For	Never Use For
Shared	Principles appearing in both sources	Keyword matches
Aligned	Semantic match passing rephrasing test	Surface similarity
Divergent	Same topic, different conclusions	Unrelated principles
Invariant	N≥2 with high alignment confidence	Any shared principle

---

Error Handling

Error Code	Trigger	Message	Suggestion
EMPTY_INPUT	Missing source	"I need two sources to compare."	"Provide two extractions or two text sources."
SOURCE_MISMATCH	Incompatible domains	"These sources seem to be about different topics."	"Comparison works best with sources covering the same domain."
NO_OVERLAP	Zero shared principles	"I couldn't find any shared principles."	"The sources may be genuinely independent, or try broader extraction."
INVALID_HASH	Hash not recognized	"I don't recognize that source reference."	"Use source_hash from a previous extraction."

---

Related Skills

• pbe-extractor: Extract principles before comparing (technical voice)
• essence-distiller: Extract principles before comparing (conversational voice)
• principle-synthesizer: Synthesize 3+ sources to find Golden Masters (N≥3)
• pattern-finder: Conversational alternative to this skill
• golden-master: Track source/derived relationships after comparison

---

Required Disclaimer

This skill compares STRUCTURE, not truth. Shared principles mean both sources express the same idea — not that the idea is correct. Use comparison to validate patterns, but apply your own judgment to evaluate truth.

---

Built by Obviously Not — Tools for thought, not conclusions.