ghm-sot-builder

SoT Builder

Create new Source of Truth files that fit your product's unique needs while maintaining template purity.

When to Use This Skill

This skill is for rare occasions (3-4 times per product lifecycle) when:

• You fork this repo and the existing SoT files don't cover your artifact types
• Your product needs to track a concept that doesn't fit existing ID prefixes
• You need to consolidate scattered documentation into a canonical SoT

Do NOT use when:

• An existing SoT file covers your need (just add entries there)
• You want to track temporary/session-specific data (use temp/ instead)
• The artifact type is already covered by ghm-id-register

Workflow Overview

1. Identify Need → Confirm no existing SoT fits
2. Design Schema → Define ID prefix, categories, required fields
3. Draft Template → Create pure structure (no methodology teaching)
4. Validate Purity → Apply the litmus test
5. Register & Integrate → Update SoT.README.md and ID system

Core Output Template

See assets/sot-template.md for the copy-paste starter template.

Element	Definition	Required
YAML Frontmatter	version, purpose, id_prefix, authority	Yes
Purpose Block	Single paragraph explaining what this tracks	Yes
Navigation Section	Category links for quick access	Yes
Entry Template	Repeatable structure for each ID	Yes
Cross-Reference Index	Bidirectional links to other SoT files	Yes
Update Protocol	When/how to add new entries	Yes

Step 1: Identify the Need

Before creating a new SoT, verify:

Checklist

• Searched existing SoT files for similar artifact types
• Confirmed the concept is durable (survives multiple sessions)
• Confirmed the concept needs unique IDs for cross-referencing
• Confirmed this isn't better served by a subsection in an existing SoT

Questions to Answer

1. What artifact type does this track?

   • Bad: "Notes" (too generic)
   • Good: "Partner Integration Contracts" (specific, durable)

2. Why can't existing SoT files handle this?

   • Valid: "We need different fields than API contracts for partner integrations"
   • Invalid: "I just want a separate file" (preference, not need)

3. What ID prefix will you use?

   • Must be unique across the system
   • 2-4 uppercase letters
   • Check SoT/SoT.UNIQUE_ID_SYSTEM.md for existing prefixes

Step 2: Design the Schema

Define the structure before writing:

ID Prefix Selection

Format: [PREFIX]-[XXX]
Examples: PIC-001, INT-042, MIG-003

Rules:

• 2-4 uppercase letters
• Descriptive but short
• Unique across all SoT files
• Check existing prefixes in SoT/SoT.UNIQUE_ID_SYSTEM.md

Category Ranges

Reserve ID ranges for logical groupings:

**Category A** (XXX-001 to XXX-099):
**Category B** (XXX-101 to XXX-199):
**Category C** (XXX-201 to XXX-299):

Required Fields per Entry

Define the minimum fields every entry needs:

Field	Purpose	Example
ID	Unique identifier	PIC-001
Title	Human-readable name	"Stripe Payment Integration"
Status	Current state	Active / Deprecated / Planned
Created	Origin date	2025-01-10
Last Updated	Last modification	2025-01-15
Related IDs	Cross-references	BR-101, API-045

Optional Fields

Add domain-specific fields as needed, but keep them structural (not methodology):

• Good: "Partner Contact" (data field)
• Bad: "Best Practices for Partner Selection" (methodology teaching)

Step 3: Draft the Template

Use assets/sot-template.md as your starting point.

Structure Sections

1. YAML Frontmatter - Metadata for the file
2. Title & Purpose Block - What this SoT tracks
3. Navigation by Category - Quick links to entries
4. Entry Template - Repeatable structure (copy for each new entry)
5. Deprecated Section - Where old entries go
6. Cross-Reference Index - Bidirectional links
7. Update Protocol - When/how to maintain

Template Purity Rules

KEEP in the template (self-documentation):

• When to add new entries
• Required fields checklist
• Cross-reference integrity checks
• File-specific maintenance procedures

MOVE to skill references (methodology teaching):

• "Best practices" for this domain
• "What makes a good entry"
• Example workflows beyond format
• Evaluation criteria

Litmus Test

For each section, ask:

"Is this teaching me how to maintain the FILE STRUCTURE, or teaching me DOMAIN KNOWLEDGE about what makes good content?"

• File structure maintenance → Keep in template
• Domain knowledge → Move to skill references

Step 4: Validate Purity

Before finalizing, run this checklist:

Purity Checklist

• No "how to analyze" or "how to evaluate" content
• No "best practices" or "key learnings" sections
• No cross-file workflows (multi-file coordination)
• No "what makes a good entry" evaluation criteria
• Examples show FORMAT only, not instructional CONTENT
• Self-documentation is under 20% of total file size

Self-Documentation Checklist

• Has "Update Protocol" section
• Documents when to add new IDs
• Includes cross-reference integrity checks
• Specifies required fields for new entries
• Self-documentation is file-specific (not generic)

Context Efficiency Checklist

• Template can be read without loading other files
• Methodology examples are in skill references, not template
• General governance references SoT.README.md

Step 5: Register and Integrate

After creating the SoT file:

Update SoT.README.md

Add entry to the structure table:

| `SoT.{YOUR_FILE}.md` | {PREFIX}-### | {Purpose description} |

Update SoT.UNIQUE_ID_SYSTEM.md

Add new prefix to Section 1.2 Standard Prefixes:

| **{PREFIX}** | {Meaning} | `SoT.{YOUR_FILE}.md` |

Create Index Tables

Add empty index table in Part 2 of SoT.UNIQUE_ID_SYSTEM.md:

#### {Your Type} ({PREFIX}-XXX)

| ID | Title | Status | Used By |
|----|-------|--------|---------|
| {PREFIX}-001 | {Title} | Active | {IDs} |

Quality Gates

Pass Checklist

• ID prefix is unique across all SoT files
• Template follows purity standard
• Update protocol included
• Cross-reference index structure defined
• SoT.README.md updated
• SoT.UNIQUE_ID_SYSTEM.md updated

Testability Check

• Can create a new entry using only the template instructions
• Cross-references can be validated programmatically
• Entries can be found by ID search

Anti-Patterns

Pattern	Example	Fix
Methodology in template	"Best practices for partner selection"	Move to skill references
Duplicate prefix	Using BR- for a new file	Choose unique prefix
Too generic	"Notes.md"	Be specific: "Partner_Integrations.md"
No update protocol	Template with no maintenance section	Add "Update Protocol" section
Orphan SoT	Not registered in SoT.README.md	Always register new files

Bundled Resources

• references/sot-patterns.md — Common patterns across existing SoT files
• references/examples.md — Before/after examples of SoT creation
• assets/sot-template.md — Copy-paste starter template

Handoff

After creating a new SoT:

1. SoT file exists at SoT/SoT.{NAME}.md
2. SoT.README.md lists the new file
3. SoT.UNIQUE_ID_SYSTEM.md has the new prefix
4. Ready to use ghm-id-register for adding entries