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

CODEBLOCK0

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

CODEBLOCK1

3. Validate Freshness

Check if derived files are current with their sources.

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

CODEBLOCK2

4. Refresh Checksums

Update metadata after manually syncing derived content.

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

CODEBLOCK3

---

Metadata Format

In-File Comments (Preferred)

Source file:
CODEBLOCK4

Derived file:
CODEBLOCK5

Standalone Manifest (Alternative)

For centralized tracking:

CODEBLOCK6

---

Checksum Specification

Algorithm: SHA256 with content normalization

Normalization steps (must be applied before hashing):

1. 1. Normalize line endings to LF (Unix style)
2. Trim trailing whitespace from each line
3. Exclude golden-master metadata comments: strip content matching <!--\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:

CODEBLOCK7

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

---

Output Schema

CODEBLOCK8

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

Error Code	Trigger	Message	Suggestion
INLINECODE8	No files found at path	"I couldn't find any files at that path."	"Check the path exists and contains files I can read."
INLINECODE9

No golden-master metadata found | "I don't see any golden-master tracking metadata." | "Run 'establish' first to set up tracking relationships." |
| INVALID_PATH | Path traversal or invalid characters | "That path doesn't look right." | "Use relative paths from project root, no '..' allowed." |
| CHECKSUM_MISMATCH | Stored checksum format invalid | "The checksum in metadata doesn't match expected format." | "Checksums should be 8+ hex characters. Was the file manually edited?" |

---

Terminology Rules

Term	Use For	Never Use For
Source	The canonical file that others derive from	Derived files
Derived

Files based on source content | Source files |
| Stale | Derived file where source checksum changed | Files without tracking |
| Fresh | Derived file where checksums match | New files |
| Tracking | Established metadata relationship | Informal references |

---

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.