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

```json
{
  "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

```json
{
  "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:

```json
"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.*