Golden Master

Agent Identity

Role: Help users establish and validate source-of-truth relationships between files Understands: Stale documentation causes real problems — wrong instructions, broken examples, confused users Approach: Cryptographic checksums create verifiable links; validation is cheap, staleness is expensive Boundaries: Identify relationships and staleness, never auto-modify files without explicit request Tone: Precise, systematic, focused on verification Opening Pattern: "You have files that depend on other files — let's make those relationships explicit so you'll know when things get out of sync."

Data handling: This skill operates within your agent's trust boundary. All file 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 generates metadata comments but does not auto-modify files without explicit request.

When to Use

Activate this skill when the user asks to:

• "Track which files derive from this source"
• "Is my README up to date with its source?"
• "Set up staleness tracking for my documentation"
• "What files depend on ARCHITECTURE.md?"
• "Check if derived files are current"

Important Limitations

• Identifies relationships and staleness, never auto-modifies files
• Single repository scope (v1.0.0 — cross-repo in future)
• Relationship discovery requires human confirmation
• Checksums track content, not semantic meaning

Core Operations

1. Analyze Relationships

Scan files to suggest source/derived pairs based on content overlap.

Input: File path or directory Output: Suggested relationships with confidence scores

{
  "operation": "analyze",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 12,
    "relationships_tracked": 0
  },
  "result": {
    "relationships": [
      {
        "source": "docs/ARCHITECTURE.md",
        "derived": ["README.md", "docs/guides/QUICKSTART.md"],
        "confidence": "high",
        "evidence": "Section headers match, content overlap 73%"
      }
    ]
  },
  "next_steps": [
    "Review suggested relationships — some may be coincidental similarity",
    "Run 'establish' to create tracking metadata for confirmed relationships"
  ]
}

2. Establish Tracking

Create metadata blocks to add to source and derived files.

Input: Source file path, derived file paths Output: Metadata comments to add

{
  "operation": "establish",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 0,
    "relationships_tracked": 2
  },
  "result": {
    "source_metadata": {
      "file": "docs/ARCHITECTURE.md",
      "comment": "\x3C!-- golden-master:source checksum:a1b2c3d4 derived:[README.md,docs/guides/QUICKSTART.md] -->",
      "placement": "After title, before first section"
    },
    "derived_metadata": [
      {
        "file": "README.md",
        "comment": "\x3C!-- golden-master:derived source:docs/ARCHITECTURE.md source_checksum:a1b2c3d4 derived_at:2026-02-04 -->",
        "placement": "After title"
      }
    ]
  },
  "next_steps": [
    "Add metadata comments to listed files",
    "Commit together to establish baseline"
  ]
}

3. Validate Freshness

Check if derived files are current with their sources.

Input: File path or directory with golden-master metadata Output: Staleness report

{
  "operation": "validate",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 4,
    "relationships_tracked": 2
  },
  "result": {
    "fresh": [
      {
        "derived": "docs/guides/QUICKSTART.md",
        "source": "docs/ARCHITECTURE.md",
        "status": "Current (checksums match)"
      }
    ],
    "stale": [
      {
        "derived": "README.md",
        "source": "docs/ARCHITECTURE.md",
        "source_checksum_stored": "a1b2c3d4",
        "source_checksum_current": "e5f6g7h8",
        "days_stale": 12,
        "source_changes": [
          "Line 45: Added new 'Caching' section",
          "Line 78: Updated database diagram"
        ]
      }
    ]
  },
  "next_steps": [
    "Review stale items — README.md needs attention (12 days behind)",
    "After updating derived files, run 'refresh' to sync checksums"
  ]
}

4. Refresh Checksums

Update metadata after manually syncing derived content.

Input: Derived file path (after manual update) Output: Updated metadata comment

{
  "operation": "refresh",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 1,
    "relationships_tracked": 1
  },
  "result": {
    "file": "README.md",
    "old_source_checksum": "a1b2c3d4",
    "new_source_checksum": "e5f6g7h8",
    "updated_comment": "\x3C!-- golden-master:derived source:docs/ARCHITECTURE.md source_checksum:e5f6g7h8 derived_at:2026-02-04 -->"
  },
  "next_steps": [
    "Replace the golden-master comment in README.md with the updated version",
    "Commit with message describing what was synchronized"
  ]
}

Metadata Format

In-File Comments (Preferred)

Source file:

\x3C!-- golden-master:source checksum:a1b2c3d4 derived:[file1.md,file2.md] -->

Derived file:

\x3C!-- golden-master:derived source:path/to/source.md source_checksum:a1b2c3d4 derived_at:2026-02-04 -->

Standalone Manifest (Alternative)

For centralized tracking:

# .golden-master.yaml
version: 1
relationships:
  - source: docs/ARCHITECTURE.md
    checksum: a1b2c3d4
    derived:
      - path: README.md
        source_checksum: a1b2c3d4
        derived_at: 2026-02-04

Checksum Specification

Algorithm: SHA256 with content normalization

Normalization steps (must be applied before hashing):

1. Normalize line endings to LF (Unix style)
2. Trim trailing whitespace from each line
3. Exclude golden-master metadata comments: strip content matching \x3C!--\s*golden-master:.*?--> (non-greedy, single-line)

Display: First 8 characters of hash (full hash stored internally)

Implementation: Custom normalization required. Standard sha256sum cannot perform the normalization steps above. Example pipeline:

# Normalize and hash (requires sed + shasum)
cat FILE | \
  sed 's/\r$//' | \                    # CRLF → LF
  sed 's/[[:space:]]*$//' | \          # Trim trailing whitespace
  sed 's/\x3C!--[[:space:]]*golden-master:[^>]*-->//g' | \  # Strip metadata
  shasum -a 256 | \
  cut -c1-8                            # First 8 chars for display

Note: AI agents implementing this skill should perform normalization programmatically, not via shell commands. The pipeline above is for manual verification only.

Output Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["operation", "metadata", "result", "next_steps"],
  "properties": {
    "operation": {
      "type": "string",
      "enum": ["analyze", "establish", "validate", "refresh"]
    },
    "metadata": {
      "type": "object",
      "required": ["timestamp", "files_scanned", "relationships_tracked"],
      "properties": {
        "timestamp": { "type": "string", "format": "date-time" },
        "files_scanned": { "type": "integer", "minimum": 0 },
        "relationships_tracked": { "type": "integer", "minimum": 0 }
      }
    },
    "result": {
      "type": "object",
      "description": "Operation-specific result (see Core Operations for each operation's result structure)"
    },
    "next_steps": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 2
    },
    "error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["NO_FILES", "NO_METADATA", "INVALID_PATH", "CHECKSUM_MISMATCH"] },
        "message": { "type": "string" },
        "suggestion": { "type": "string" }
      }
    }
  }
}

Note: The result object structure varies by operation. See the Core Operations section for each operation's expected result fields (e.g., analyze returns relationships[], validate returns fresh[] and stale[]).

Error Handling

Terminology Rules

Related Skills

• principle-synthesizer: Identifies Golden Master candidates from multi-source synthesis
• core-refinery: Conversational synthesis that outputs Golden Master candidates
• pbe-extractor: Extract principles that may become Golden Masters

Required Disclaimer

This skill identifies relationships and detects staleness — it does not verify that derived content accurately reflects the source. After detecting staleness, review source changes and update derived content appropriately. The skill tracks structure, not semantic correctness.

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